Skip to main content

Full text of "DTIC ADA1031608: INGRES Version 6.2 Reference Manual."

See other formats


AD-A103 160 CALIFORNIA UNIV BERKELEY ELECTRONICS RESEARCH LAB F/6 5. 

INGRES VERSION 6.2 REFERENCE MANUAL.(U) 

JUL 79 J KOODFILL* N WHYTE* M UBELL* P SIESEL N00014-78-C-0185 
UNCLASSIFIED UCB/ERL-M79/43 NL 






























i\ 

< 1 . \\ 








( 


LEVEL 


/ ' 



INCHES VERSION 6.2 REFERENCE rlANUAL 


I 




11 3==Si 

- —4=4 


John Woodfill, Nick Whyte, Mike Shell, Polly Siegel 
Dan Rlea, Marc Meyer, Paula Hawthorn, Bob Epstein, 
Rick Berman, and Eric All.nan 


Hi SE 




stoii 


fen m 


PP" 


pi 


Memorandum No. UCB/ERL M79/43 


V 


PtSTKBUTION ST A TEMENT A 

Approved tor public relea*#; 
Diitribuiion Unlimited 


QELECtZi 

^^AUG 20 19811 




ELECTRONICS RESEARCH LABORATORY 

College ef Engineering 

University el California, Berkeley, CA 94720 

81 8 i9 088 







1 

I 


INGRES 

VERSION 6.2 

REFERENCE MANUAL , 

7/20/79 


by 


f 




' 

John/Woodfill 
Nick /Whyte 
, Mike'Ubeli f 

i Polly/Siegel / 

Dan/Ries ' 
—Man. Ml$TT 
Paula Hawthorn 
Bob Epstein 
Rick Berman 
Eric Allman 



Memorandum Wo/ UCB/ERL-M79/43 
20 Jul|*i979 








Q'P - ' ; ' 7 i-- i}}^_ /: 

7 FHiG 2 £-'/? c -a>± ,r 7? 

ELECTRONICS RESEARCH LABORATORY 



j Accession For 

| NT1S GRA&l 
DTIC TAB f. 

Unannounced j 

l Justification.^__. 

pA~* l£- & 

By- 

Distribution/ 

Availability Codes 
Avail and/or 
Dlst Special 

i l 

\fi ! 

I_L 


College of Engineering 
University of California, Berkeley 
94720 


ssnsso . , 


“•-i .*** 




aaa 


a 





Research Sponsored by the Air Force Office of Scientific Research / 
Grant 78-3596, U. S. Army Research Office Grant DAAG29-76-G-0245/ 
Office of Naval Research Contract N00014-78-C-U185, National Science 
Foundation Grant MCS75-03839-A01, and Joint Services Electronics 
Program Contract F49620-79-C-0178. 








INTRODUCTION (INGRES) 


3/15/79 


INTRODUCTION (INGRES) 


This manual is a reference manual for the INGRES data base system. It documents the use of 
ingris in a very terse manner. To learn how to use INGRES, refer to the document called "A 
Tutorial on ingki s". 

The Ingres reference manual is subdivided into four parts: 

Quel describes the commands and features which are used inside of INGRES. 

Unix describes the Ingres programs which are executable as UNIX commands. 

Files describes some of the important files used by INGRES. 

Error lists all the user generatable error messages along with some elaboration as to what 
they mean or what we think they mean. 

Each entry in this manual has one or more of the following sections: 

NAME section 

This section repeats the name of the entry and gives an indication of its purpose. 
SYNOPSIS section 

This section indicates the form of the command (statement). The conventions 
which are used are as follows: 

Bold face names are used to indicate reserved keywords. 

Lower case words indicate generic types of information which must be sup¬ 
plied by the user; legal values for these names are described 
in the DESCRIPTION section. 

Square brakets ( (] ) indicate that the enclosed item is optional. 

Braces ( () ) indicate an optional item which may be repeated. In some cases 
they indicate simple (non-repeated) grouping; the usage 
should be clear from context. 

When these conventions are insufficient to fully specify the legal format of a com¬ 
mand a more general form is given and the allowable subsets are specified in the 
DESCRIPTION section. 

DESCRIPTION section 

This section gives a detailed description of the entry with references to the generic 
names used in the SYNOPSIS section. 

EXAMPLE section 

This section gives one or more examples of the use of the entry. Most of these ex¬ 
amples are based on the following relations: 

emp(name.sal.mgr.bdate) 

and 

ne wemp( name.sal.age) 
and 

parts(pnum, pname. color, weight, qoh) 

SEE ALSO section 

This section gives the names of entries in the manual which are closely related to 
the current entry or which are referenced in the description of the current entry. 

BUGS section 

This section indicates known bugs or deficiencies in the command. 

To start using INGRES you must be entered as an INGRES user; this is done by the INGRES ad- 
minisiraior who will enter you in the "users" file (see users(files)). To start using ingres see the 
section on ingres(unix), quel(quel), and monitor(quel). 

\( kNOWI.KfW.EMENTS 

We would like to acknowledge the people who have worked on INGRES in the past: 

William Zook 
Karel Youssefi 
Peter Rubinstein 








INTRODUCTION (INGRES) 3/15/79 


Peier Kreps 
Gerald Held 
James Ford 


footnoti: 

Unix is a trademark of Bell Laboratories. 


INTRODUCTION (INGRES) 


-2* 





TABLE OF CONTENTS (INGRES) 


3 / 23/79 


TABLE OF CONTENTS v NGRES) 


APPEND(Ql)EL) - append tuples to a relation 

append (tol relname ( target list) (where quail 

COPY (Ql)EL) — copy data into/from a relation from/into a UNIX file, 
copy relname (domname = format j, domname * format }) 
direction "filename" 

CREATE(QUEL) - create a new relation 

create relname domname / = format (, domname2 ** format |) 

DEFINE(QUEL) -- define subscnema 

define view name (target list) [ where qual ] 
define permit oplist { on j of | to } var { (attlist) } 
to name t at term 1 [ from time to time ) 

[ on day to day ] [ where qual ) 
define integrity on var is qual 

DELETE(QUEL) — delete tuples from a relation 
delete tup!e_variable [where qual) 

DESTROY(QUEL) — destroy existing relalion(s) 
destroy relname {, relname) 

destroy [permit | integrity] relname [integer [, integer}) all) 

HELP(QUEL) - get information about how to use INGRES or about relations in the database, 
help [relnamel ["section"] (, relname}{, "section") 
help view [relname {, relname]] 
help protect ( relname {, relname}] 
help Integrity Irelname {, relname}! 

INDEX (QUEL) - create a secondary index on an existing relation, 
index on relname is indexname (domain / ( ,domain2}) 

INTEGRITY(QUEL) — define integrity constraints 

define integrity on var is qual 

MACROS(QUEL) — terminal monitor macro facility 

MODIFY(QUEL) — convert the storage structure of a relation 
modify relname to storage-structure 

[on keyl [ . sortorder ] [ | , key2 [ : sortorder ] } ] ] 

[ where [ fillfactor = n ) t , minpages = n ] 

( , maxpages = nn] ] 

MONITOR (QUEL) - interactive terminal monitor 

PERMIT(QUEL) — add permissions to a relation 

define permit oplist { on | of | to } var [ (attlist) ] 
to name [ at term ] [ from time to time ] 

[ on day to day } [ where qual} 

PRINT(QUEL) - print relation(s) 
print relname |, relname) 

QUEL(QUEL) - QUEry Language for INGRES 

RANGE(QUEL) - declare a variable to range over a relation 
range of variable is relname 

REPLACE(QUEL) - replace values of domains in a relation 
replace tuple_variable (targetjist) [where qual] 

RETRIEVE(QUEL) - retrieve tuples from a relation 

retrieve [[into] relname] (targetjist) [where qual] 
retrieve unique (targetjist) [where qua)] 




TABLE OF CONTENTS (INGRES) 


3/23/79 


TABLE OF CONTENTS (INGRES) 


SAVE(QUEL) — save a relation until a date, 
save relname until month day year 

VIEW(QUEL) - define a virtual relation 

define view name (target-list) [ where quat ] 

COPYDB(UNIX) - create batch files to copy out a data base and restore it. 

copydb [ —u name] database full-path-name-of-directory 1 relation ... 1 

CREATDB(UNIX) — create a data base 

creatdb l — uname 1 ( —e 1 ( —m ] ( ±c ] [ ±q 1 dbname 

DESTROYDB(UNIX) - destroy an existing database 
destroydb [ — s ) [ — m ) dbname 

EQUEL(UNIX) - Embedded QUEL interface to C 
equel I —d ] t —f 1 ( —r ) file.q ... 

GEO-QUEL(UNIX) - GEO-QUEL data display system 

geoquel { —s ] ( —d 1 ( —a ] ( — 17*I I —tnTj dbname 

HELPR(UNIX) - get information about a database. 

helpr 1 —u name] 1 ±w ] database relation ... 

INGRES(UNIX) - INGRES relational data base management system 
Ingres l flags ] dbname [ process_table 1 

PRINTR(UNIX) - print relations 

prinlr [ flags] database relation ... 

PURGE(UNIX) - destroy all expired and temporary relations 

purge [ — f 1 [ — p ] [ — a 1 l — s 1 [ ±w ) ( database ... ) 

RESTORE(UNIX) - recover from an INGRES or UNIX crash, 
restore [ —a 1 [ —s 1 [ ±w ] ( database ... j 

SYSMOD(UNIX) - modify system relations to predetermined storage structures. 

sysmod [ — s 1 [ —w ] dbname ( relation ] l attribute ] [ indexes 1 [ tree ] [ protect ] 
[ integrities ] 

TIMEFIX(UNIX) - patch INGRES binary code for correct timezone. 
timefix [ — u 1 [ —s/V] I — tyyyzzz] l — dX] filename ... 

USERSETUP(UNIX) - setup users file 
.../bin/usersetup l pathname 1 

DAYFILE(FILES) - INGRES login message 

DBTMPLT(FILES) - database template 

ERROR(FILES) - files with INGRES errors 

GRAFILE(FILES) - GEO-QUEL login message 

LIBQ(FILES) - Equel run-time support library 

PROCTAB(FILES) - INGRES runtime configuration information 

STARTUP!FILES) - INGRES startup file 

TTYTYPE(FILES) - GEO-QUEL terminal type database 

USERS(FILES) - INGRES user codes and parameters 

INTRODUCTION(ERROR) - Error messages introduction 

EQUEL(ERROR) - EQUEL error message summary 
Error numbers 1000 - 1999. 

PARSER(ERROR) - Parser error message summary 
Error numbers 2000 — 2999. 



TABLE OF CONTENTS (INGRES) 


3/23/79 


TABLE OF CONTENTS l INGRES ) 


QRYMOD(ERROR) - Query Modification error message summary 
Error numbers 3000 - 3999 

OVQP(ERROR) — One Variable Query Processor error message summary 
Error numbers 4000 - 4499. 

DECOMP(ERROR) - Decomposition error message summary 
Error numbers 4500 - 4999. 

DBU(ERROR) - Data Base Utility error message summary 
Error numbers 5000 - 5999 

GEOQUEL (ERROR) - GEO-QUEL error message summary 
Error numbers 30000 - 30999. 



COPY(QUEL) 


1/19/79 


COPY(QUEL) 


name 

copy — copy data into/from a relation from/into a UNIX file. 

SYNOPSIS 

copy relname (domname = format [, domname = formal |) 
direction "filename" 

DESCRIPTION 

Copy moves data between INGRES relations and standard UNIX files. Relname is the name of an 
existing relation. In general domname identifies a domain in relname. Formal indicates the for¬ 
mal the UNIX file should have for the corresponding domain. Direction is either into or from. 
Filename is the full UNIX pathname of the file. 

On a copy from a file to a relation, the relation cannot have a secondary index, it must be 
owned by you, and it must be updatable (not a secondary index or system relation). 

Copy cannot be used on a relation which is a view. For a copy into a UNIX file, you must either 
be the owner of the relation or the relation must have retrieve permission for all users, or all 
permissions for all users. 

The formats allowed by copy are: 

il,i2,i4 — The data is stored as an integer of length 1, 2, or 4 bytes in the UNIX file. 

f4,f8 — The data is stored as a floating point number (either single or double precision) in the 
Unix file. 

cl,c2.c255 — The data is stored as a fixed length string of characters. 

cO — Variable length character string. 
dO,dl.d255 — Dummy domain. 

Corresponding domains in the relation and the UNIX file do not have to be the same type or 
length. Copy will convert as necessary. When converting anything except character to charac¬ 
ter, copy checks for overflow. When converting from character to character, copy will blank pad 
or truncate on the right as necessary. 

The domains should be ordered according to the way they should appear in the UNIX file. 
Domains are matched according to name, thus the order of the domains in the relation and in 
the UNIX file does not have to be the same. 

Copy also provides for variable length strings and dummy domains. The action taken depends 
on whether it is a copy into or a copy from. Delimiters for variable length strings and for dum¬ 
my domains can be selected from the list of: 

nl — new line character 
tab - tab character 
sp — space 

nul or null — null character 

comma — comma 

colon — colon 

dash — dash 

Iparen - left parenthesis 

rparen - right parenthesis 

.v — any single character V 

The special meaning of any delimitor can be turned off by preceeding the delimitor with a 
The delimitor can optionally be in quotes Cdelim"). This is usefully if you wish to use a single 
character delimitor which has special meaning to the quel parser. 

When the direction is from, copy appends data into the relation from the UNIX file Domains in 
the INGRES relation which are not assigned values from the UNIX file are assigned the default 
value of zero for numeric domains, and blank for character domains. When copying in this 


- 1 - 


i 


APPEND (QUEL) 


1 / 26/79 


APPEND (QUEL) 


\ WIF 

append — append tuples to a relation 
S\ NOPSIS 

append [to] relname Uargeijist) [where qual] 

DESCRIPTION 

Append adds tuples which satisfy the qualification to relname. Relname must be the name of an 
existing relation. The target list specifies the values of the attributes to be appended to relname. 
The domains may be listed in any order. Attributes of the result relation which do not appear 
in the targetJist as result attnames (either explicitly or by default) are assigned default values 
of 0. for numeric attributes, or blank, for character attributes. 

Values or expressions of any numeric type may be used to set the value of a numeric type 
domain. Conversion to the result domain type takes place. Numeric values cannot be directly 
assigned to character domains. Conversion from numeric to character can be done using the 
ascii operator (see quel(quel)). Character values cannot be directly assigned to numeric 
domains. Use the inti, int2, etc. functions to convert character values to numeric (see 
quel(quel)). 

The keyword all can be used when it is desired to append all domains of a relation. 

An upper hi may only be issued by the owner of the relation or a user with append permission on 
the given relation. 

EXAMPLE 

/• Make new- employee Jones work for Smith »/ 
range of n is newemp 

append to emp(n.name,n.sal, mgr = "Smith", bdate = 1975-n.age) 
where n.name = "Jones" 

/* Append the newempl relation to newemp */ 
range of nl is newempl 
append to newemp(nl.all) 


SEE ALSO 

copy(quel), permit(quel), quel(quel), retrieve(quel) 


DIAGNOSTICS 

Use of a numeric type expression to set a character type domain or vice versa will produce diag¬ 
nostics. 


Bt <,s 

Duplicate tuples appended to a relation stored as a "paged heap” (unkeyed, unstructured) are 
not removed. 




COPY ( 01 I L ) 


1/19/79 


COPY(QUEL) 


direction the following speei.il meanings apply 

c0iA7//»/ - The data in the t six tile is a variable length character string terminated by me del- 
imitor (h’liin. It lichm is missing then the first comma, tab, or newline encountered 
will terminate the string The delimitor is not copied 

For example: 

pnum- cO — string ending in comma, tab. or nl. 

pnum = c(lnl — siring ending in nl. 

pnum = cOsp — siring ending in space. 

pnum = cO' Z" - siring ending in the character "Z". 

pnum = cO"%" - siring ending in the character 

A delimitor can be escaped by preceeding it with a ‘V- For example, using name = 
cO, the string "Blown, Joe," will be accepted into the domain as "Blow, Joe". 

dO del/m — The data in the i MX tile is a variable length character string delimited by dchni. The 
string is read and discarded. The delimitor rules are identical for cO and dll. The 
domain name is ignored. 

dl.d2.d255 — The data in the c MX tile is a fixed length character string. The string is read 

and discarded. The domain name is ignored. 

When the direction is into, copy transfers data into the UNIX file from the relation. If the file 
already existed, it is truncated to zero length before copying begins. When copying in this 
direction, the following special meanings apply: 

cO - The domain value is converted to a fixed length character string and writted into the UNIX 
file. For character domains, the length will be the same as the domain length. For 
numeric domains, the standard tNGRts conversions will take place as specified by the 
i\ * —f, and c' flags (see ingres(unix)). 

cOr/r ’Iihi - The domain will be converted according to the rules for cO above. The one charac¬ 
ter delimitor will be inserted immediately after the domain. 

dl,d2,...,d255 - The domain name is taken to be the name of the delimitor. It is written into 
the UNIX file 1 time for dl, 2 times for d2, etc. 

dO - This format is ignored on a copy into. 

dO iicUm — The deli)n is written into the file. The domain name is ignored. 

If no domains appear in the copy command lie. copy relname 0 into/from "filename") then 
copy automatically does a "bulk" copy of all domains, using the order and format of the domains 
in the relation. This is provided as a convenient shorthand notation for copying and restoring 
entire relations. 

To copy into a relation, you must be the owner or all users must have all permissions set. 
Correspondingly, to copy from a relation you must own the relation or all users must have at 
least retrieve permission on the relation. Also, you may not copy* view. 

t X VMI’I t 

/■ Copy data into the emp relation »/ 
copy emp (name = cl().sal = f4,bdate — i2.mgr = cl0,x.xx=dl) 
from "/mnt/me/myfile" 

/* Copy employee names and their salaries into a file */ 
copy emp (name = c0.comma = dI.sal = cO,nl = dlI 
into "/mnt/you/yourfilc" 

/* Bulk copy employee relation into file */ 
copy emp 0 

into "/mnt/ours/ourfile" 




COPY(QUEL) 


1/19/79 


COPY(QUEL) 


/< Bulk copy employee relation from file */ 
copy emp () 

from "/mnt/thy/thyfile" 

\lso 

append(quel). create(quel), quel(quel), permit(quel), view(quel), ingres(unix) 

HI t.S 

Copy stops operation at the first error. 

When specifying filename, the entire UNIX directory pathname must be provided, since Ingres 
operates out of a different directory than the user's working directory at the time INGRES is in¬ 
voked. 






1 

LRLAitiybtL) 


v wit 

create - create a new relation 
*s\ munis 

create relname (domname/ = formal domname-’ = format |> 

1)1 SI RIIM ION 

(■/!(//(■ will enter a new iclation into the data base The relation will be "owned” by 'he user and 
will be set to expire alter seven days I he name of the relation is n liuime and the domains are 
named Jonuuwu l . iloimuiwr'. etc I he domains are created with the type specified by Ionian. 
Formats are described in the quel(quel) manual section. 

The relation is created as a paged heap with no data initially in it. 

A relation can have no more than 49 domains. A relation cannot have the same name as a sys¬ 
tem relation. 

IWMPU. 

/* Create relation emp with domains name, sal and bdate */ 
create emp (name = elO. salary = l'4. bdate = i2) 

SFF \LSO 

append(quel), copy(quel), destroy (quel), save(quel) 

BK.s 


CRtAlhtgilLL) 


1/26/79 


1 

J 







DEFINE (QUEL) 


2/7/79 


DEFINE (QUEL) 


define ~ define subschema 

SI \OPSIS 

define view name (target list) I where qua! | 
define permit oplist | on | of | to ) var ( (atilisi) ] 
to name l at term I [ from time to time I 
( on day to day ] ( where qual ) 
define integrity on var is qual 

IH St. Rll'l to\ 

The ilvhw statement creates entries for the subschema definitions. See the manual sections 
listed below for complete descriptions of these commands. 

SKF Al.SO 

integrity (quel). perniit(quel). view(quel) 






DELHI!-; (QIJEI.) 


1/26/79 


DELETE(QUEL) 


NXMt 

delete — delete tuples from a relation 

SWOPSIS 

delete tuplevariable [where qual] 

DESCRIPTION 

Delete removes tuples which satisfy the qualification qua I from the relation that they belong to. 
The tuple variable must have been declared to range over an existing relation in a pievious 
ran tie statement. Delete does not have a <araet_hst. The delete command requires a tuple vari¬ 
able from a range statement, and not the actual relation name. If the qualification is not given, 
the effect is to delete all tuples in the relation. The result is a valid, but empty relation 

To delete tuples from a relation, you must be the owner of the relation, or have delete permis¬ 
sion on the relation. 


i:\.\mpi.k 

/• Remove all employees who make over $30,000 */ 
range of e is emp 
delete e where e.sal > 30000 

sFK AI.SO 

deslroy(quel), permit(quel), quel(quel), range(quel) 

BK.S 


- I 


■5 








DESTROY IQUEL I 


2/21/79 


DES1 KOX t QUt-L ) 


S VNU 

destroy - destroy existing relation(s) 

SX NOPStS 

destroy reiname (. reiname) 

destroy (permit) integrity] reiname (integer (. integer}) all) 

DESCRIPTION 

Destroy removes relations from the data base, and removes constraints or permissions from a 
relation. Only the relation owner may destroy a relation or its permissions and integrity con¬ 
straints. A relation may be emptied of tuples, but not destroyed, using the delete statement or 
the modify statement. 

If the relation being destroyed has secondary indices on it, the secondary indices are also des¬ 
troyed. Destruction of just a secondary index does not affect the primary relation it indexes. 

To destroy individual permissions or constraints for a relation, the integer arguments should be 
those printed by a help permit (for destroy permit) or a help integrity (for destroy integrity) 
on the same relation. To destroy all constraints or permissions, the all keyword may be used in 
place of individual integers. To destroy constraints or permissions, either the integer arguments 
or the all keyword must be present. 

EXAMPLE 

/• Destroy the emp relation •/ 
destroy emp 
destroy emp, parts 

/• Destroy some permissions on parts, and all integrity 
• constraints on employee 

*/ 

destroy permit parts 0, 4, 5 
destroy integrity employee 

SEE ALSO 

create (quel), delete(quel), help(quel), index(quel), modify(quel) 


Ill l l'iyt i;i ) 


2/21/79 


HELP(QUEL) 


\\\lt 

help gel information about how in use im.KIn or about relations in the database. 

SVSOPMS 

help t relname! ("section"! !. relname}!, “section"} 
help view Irelname !. relnamejl 
help protect ( relname |, relname!) 
help intejjrity Irelname !. telnamc)! 

m:si 'kiption 

Help may be used to obtain sections of this manual, information on the content of the current 
data base, information about specific relations in the data base, view detinitions, or protection 
and integrity constraints on a relation The legal forms are as follow: 

help "settion " ~ Produces a copy of the specified section of the INGRES Reference Manual, and 
prints it on the standard output device. 

help - Gives information about all relations that exist in the current database, 
help relname (. relname } — Gives information about the specified relations, 
help — Gives the table of contents. 

help view relname (. relname I — Prints view definitions of specified views. 

help protect relname (, relname } — Prints permissions on specified relations. 

help integrity relname [. relname } — Prints integrity constraints on specified relations. 

The protect and integrity forms print out unique identifiers for each constraint. These 
identifiers may be used to remove the constraints with the destroy statement. 

EXAMPLE 

help 

help help /* prints this page of the manual */ 
help quel 
help emp 

help emp, parts, "help", supply 
help view overp view 
help protect parts, employee 
help integrity parts, employee 

SEE AI.SO 

destroy(quel) 


BIOS 


Alphabetic^ appearing within the section name must be in lower-case to be recognized. 








INDEX(QUEL) 


2/21/79 


INDEX (QUEL) 


\ \Mt. 

index - create a secondary index on an existing relation. 
se NOPSIS 

index on relnanne is indexname (domain / ( .domain 2)) 

DESCRIPTION 

Index is used to create secondary indices on existing relations in order to make retrieval and up¬ 
date with secondary keys more efficient. The secondary key is constructed from relname 
domains 1, 2.6 in the order given. Only the owner of a relation is allowed to create secon¬ 

dary indices on that relation. 

In order to maintain the integrity of the index, users will NOT be allowed to directly update 
secondary indices. However, whenever a primary relation is changed, its secondary indices will 
be automatically updated by the system. Secondary indices may be modified to further increase 
the access efficiency of the primary relation. When an index is first created, it is automatically 
modified to an isam storage structure on all its domains, if this structure is undesirable, the 
user may override the default isam structure by using the — n switch (see ingres(unix)), or by 
entering a modify command directly. 

If a modify or destroy command is used on relname , all secondary indices on relname are des¬ 
troyed. 

Secondary indices on other indices, or on system relations are forbidden. 

EXAMPLE 

/« Create a secondary index called "x” on relation “emp" */ 
index on emp is x(mgr,sal) 

nEF ALSO 

copy (quel), destroy(quel), modify(quel) 

BIOS 

At most 6 domains may appear in the key. 

The ropy command cannot be used to copy into a relation which has secondary indices. 

The default structure isam is a poor choice for an index unless the range of retrieval is small. 





INTEGRII V ( QUEL.) 


2/7/79 


INTEGRITY (QUEL.) 


\ \Mt 

integrity - define integrity constraints 
sy \opnis 

define integrity on var is qual 
DK.St RIPTION 

The linearity statement add an integrity constraint for the relation specified by var. After the 
constraint is placed, all updates to the relation must satisfy qua!. Qua I must be true when the 
linearity statement is issued or else a diagnostic is issued and the statement is rejected. 

In the current implementation, linearity constraints are not Ragged - bad updates are simply 
(and silently) not performed. 

Qiuil must be a single variable qualification and may not contain any aggregates. 

linearity statement may be issued only by the relation owner. 
example: 

/* Ensure all employees have positive salaries «/ 
range of e is employee 
define integrity on e is e.salary > 0 

SEE \I.SO 

destroy (quel) 


\ 

\ 








MACROS (QUEL) 


2/19/79 


MACROS (QUEL ) 


VV'lt 

macros — terminal monitor macro facility 

DESCRIPTION 

The terminal monitor macro facility provides the ability to tailor the QUEL language to the 
user’s tastes. The macro facility allows strings of text to be removed from the query stream 
and replaced with other text. Also, some built in macros change the environment upon execu¬ 
tion. 

Basic Concepts 

All macros are composed of two parts, the template part and the replacement part. The template 
part defines when the macro should be invoked. For example, the template “ret” causes the 
corresponding macro to be invoked upon encountering the word “ret” in the input stream. 
When a macro is encountered, the template part is removed and replaced with the replacement 
part. For example, if the replacement part of the “ret” macro was “retrieve”, then all in¬ 
stances of the word "ret” in the input text would be replaced with the word “retrieve”, as in 
the statement 

ret (p all) 

Macros may have parameters, indicated by a dollar sign. For example, the template “get SI” 
causes the macro to be triggered by the word “get” followed by any other word. The word fol¬ 
lowing "get” is remembered for later use. For example, if the replacement part of the “get" 
macro where 

retrieve (p all) where p.pnum = SI 

then typing "get 35” would retrieve all information about part number 35. 

Defining Macros 

Macros can be defined using the special macro called “define". The template for the define 
macro is (roughly) 

(define; St; Sr} 

where St and Sr arc the template and replacement parts of the macro, respectively. 

Let's look at a few examples. To define the “ret" macro discussed above, we would type: 
(define; ret; retrieve! 

When this is read, the macro processor removes everything between the curly braces and up¬ 
dates some tables so that "ret” will be recognized and replaced with the word “retrieve". The 
define macro has the null string as replacement text, so that this macro seems to disappear. 

A useful macro is one which shortens range statements. It can be defined with 

(define; rg Sv Sr; range of Sv is Sr! 

This macro causes the word “rg” followed by the next two words to be removed and replaced 
by the words “range of", followed by the first word which followed “rg", followed by the word 
“is”, followed by the second word which followed "rg”. For example, the input 

rg p parts 

becomes the same as 

range of p is parts 

Evaluation Times 

When you type in a define statement, it is not processed immediately, just as queries arc saved 
rather than executed. No macro processing is done until the query buffer is evaluated. The 
commands \go. Mist, and \eval evaluate the query buffer. \go sends the results to im,ri s. list 
prints them on your terminal, and \eval puts the result back into the query buffer. 







MACROS < Ql'KL > 


2/19/79 


MACROS(QUEL) 


li is important u> evaluate am define statements, or it will be exactly like you did r.ai type them 
in m all A common way 10 define macros is to type 

idefine . . . ! 

\eval 

\reset 

If the \eval was left out. there is no effect at all. 

Quoting 

Sometimes strings must be passed through the macro processor without being processed. In 
such cases the grave and acute accent marks (' and *) can be used to surround the literal text. 
For example, to pass the word "ret'' through without converting it to "retrieve” we could type 

ret' 

Another use for quoting is during parameter collection. If we want to enter more than one 
word where only one was expected, we can surround the parameter with accents. 

The backslash character quotes only the next character (like surrounding the character with ac¬ 
cents). In particular, a grave accent can be used literally by preceeding it with a backslash 

Since macros can normally only be on one line, it is frequently useful to use a backslash at the 
end of the line to hide the newline. For example, to enter the long "get” macro, you might 
type: 

[define; get $n. retrieve te.all) \ 
where e.name = "Sn"! 

The backslash always quotes the next character even when it is a backslash. So, to get a real 
backslash, use two backslashes. 

More Parameters 

Parameters need not be limited to the word following. For example, in the template descriptor 
for define: 

{define, Sf, Sri 

the St parameter ends at the first semicolon and the Sr parameters ends at the first right curly 
brace. The rule is that the character which follows the parameter specifier terminates the 
parameter, if this character is a space, tab, newline, or the end of the template then one word is 
collected 

As with all good rules, this one has an exception. Since system macros are always surrounded 
by curly braces, the macro processor knows that they must be properly nested. Thus, in the 
statement 

idefine. x; Jsysfn i} 

The first right curly brace will close the "sysfn" rather than the "define” Otherwise this 
would have to be typed 

idefine; x. 'isyslnil 

Words are defined in the usual way. as strings of letters and digits plus the underscore charac¬ 
ter 

Other Kuiltin Macros 

There are several other macros built in to the macro processor In the following description, 
some of the parameter specifiers arc marked with two dollar signs rather than one; this will be 
discussed in the section on prescanning below. 

idefine. SSt: SSr, defines a macro as discussed above. Special processing occurs on the template 
part which will be discussed in a later section. 





MACROS (QUEL > 


2/19/79 


MACROS (QUEL) 


1 rattle tine. SSt; SSr| is another form of define, where the special processing does not take 
place. 

[remove; SSn| removes the macro with name Sn. it can remove more than one macro, since it 
actually removes all macros which might conflict with Sn under some circumstance. For exam¬ 
ple. typing 

[define, get part Sn; . . . 1 
[define; get emp Sx; . . . j 
[remove; getj 

would cause both the get macros to be removed. A call to 
[remove; get part) 

would have only removed the first macro. 

[type S$s! types $s onto the terminal. 

[read SSs| types $s and then reads a line from the terminal. The line which was typed replaces 
the macro. A macro called "[readcount)” is defined containing the number of characters read. 
A conirol-D (end of file) becomes -1, a single newline becomes zero, and so forth. 

[readdefine; $$n; SSs) also types Ss and reads a line, but puts the line into a macro named Sn. 
The replacement text is the count of the number of characters in the line, [readcount) is still 
defined. 

[ifsame; $$a; S$b; $t; Sf) compares the strings Sa and Sb. If they match exactly then the re¬ 
placement text becomes St, otherwise it becomes Sf. 

iifeq; SSa; $$b; St, Sf) is similar, but the comparison is numeric. 

[ifgt; SSa; $$b; St; Sf) is like ifeq, but the test is for Sa strictly greater than Sb. 

[subsir. SSf; $$t, SSs) returns the part of Ss between character positions Sf and St, numbered 
from one. If Sf or St are out of range, they are moved in range as much as possible. 

[dump. SSn) returns the value of the macro (or macros) which match Sn (using the same algo¬ 
rithm as remove) The output is a rawdefine statement so that it can be read back in. [dump) 
without arguments dumps all macros. 

Metacharacters 

Certain characters are used internally. Normally you will not even see them, but they can ap¬ 
pear in the output of a dump command, and can sometimes be used to create very fancy mac¬ 
ros. 

| matches any number of spaces, tabs, or newlines. It will even match zero, but only between 
words, as can occur with punctuation. For example, \| will match the spot between the last 
character of a word and a comma following it. 

matches exactly one space, lab, or newline. 

& matches exactly zero spaces, tabs, or newlines, but only between words. 

The Define Process 

When you define a macro using define, a lot of special processing happens. This processing is 
such that define is not functionally complete, but still adequate for most requirements. If more 
power is needed, rawdefine can be used; however, rawdefine is particularly difficult to use 
correctly, and should only he used by gurus. 

In define, all sequences of spaces, labs, and newlines in the template, as well as all non- 
spaces" between words, arc turned into a single \| character If the template ends with a 
parameter, the \& character is added at the end. 

If you want to match a real tab or newline, you can use \t or \n respectively. For example, a 
macro which reads an entire line and uses it as the name of an employee would be defined with 


- 3 - 




MACROS (QUEL) 


2/19/79 


MACROS (QUEL) 


{define; gel Sn\n; \ 

ret (c all) where c.name =■ "So"! 

t his macro might he used b> typing 

gel 'Sian* 

lo get all information about everyone with a name which included “Stan". By the way, notice 
that it is ok to nest the “ret" macro inside (he “get" macro. 

Parameter Presean 

Sometimes it is useful to macro process a parameter before using it in the replacement part 
This is particularly important when using certain builtin macros. 

For prescan to occur, two things must be true: first, the parameter must be specified in the 
template with two dollar signs instead of one, and second, the actual parameter must begin with 
an “at” sign (“@”) (which is stripped off). 

For an example of the use of prescan, see "Special Macros" below. 

Special Macros 

Some special macros are used by the terminal monitor to control the environment and return 
results to the user. 

Ibegintrap) is executed at the beginning of a query. 

(endtrap) is executed al ter the body of a query is passed to inorhs 

{continuetrap) is executed alter the query completes. The difference between this and endtrap 
is that endtrap occurs after the query is submitted, but before the query executes, whereas con- 
tinuetrap is executed after the query executes. 

'editor) can be defined to be the pathname of an editor to use in the \edit command. 

{shell} can be defined to be the pathname of a shell to use in the \shell command. 

'luplccountl is set after every query (but before continuetrap is sprung) to be the count of the 
number of tuples which satisfied the qualification of the query in a retrieve, or the number of 
tuples changed in an update, it is not set for DBU functions. If multiple queries are run at 
once, it is set to the number of tuples which satisfied the last query run 

For example, lo print out the number of tuples touched atilt .rtatically after each query, you 
could enter: 

{define; jbegintrap); {remove; {tuplecounl))) 

{define; {continuetrap); \ 

{ifsame; @{tuplecounl); {tuplecounl);; \ 

{type @{tuplccount) tuples touched))) 

si t. also 

monitor(quel) 


\ 




MODIFY (QUEL) 


2/23/79 


MODIFY (QUEL) 


WMF 

modify — convert the storage structure of a relation 

sv NOPSIS 

modify relname to storage-structure ( on key l 1 : soriorder 1 ( { . key2 ( : soriorder ) ) ) ] I 

where [ fillfactor = //)[. ininpages = //)!, maxpages = n 1 ] 


DFS( RIPTION 

Relname is modified to the specified storage structure. Only the owner of a relation can modify 
that relation. This command is used to increase performance when using large or frequently 
referenced relations. The storage structures are specified as fallows 

isam — indexed sequential storage structure 

eisam — compressed isam 

hash — random hah storage structure 

chash - compressed hash 

heap — unkeyed and unstructured 

cheap — compressed heap 

heapsort — heap with tuples sorted and duplicates removed 
cheapsort — compressed heapsort 
truncated - heap with all tuples deleted 

The paper "Creating and Maintaining a Database in ingrks" (ERL Memo M77 — 71) discusses 
how to select storage structures based on how the relation is used. 

The current compression algorithm only suppresses trailing blanks in character fields. A more 
effective compression scheme may be possible, but tradeoffs between that and a larger and 
slower compression algorithm are not clear. 

If the on phrase is omitted when modifying to isam, cisam, hash or chash, the relation will au¬ 
tomatically be keyed on the first domain. When modifying to heap or cheap the on phrase must 
be omitted. When modifying to heapsort or cheapsort the on phrase is optional. 

When a relation is being sorted (isam, cisam, heapsort and cheapsort). the primary sort keys 
will be those specified in the on phrase (if any). The first key after the on phrase will be the 
most significant sort key and each successive key specified will be the next most significant sort 
key. Any domains not specified in the on phrase will be used as least significant sort keys in 
domain number sequence. 

When a relation is modified to heapsort or cheapsort, the soriorder can be specified to be as¬ 
cending or descending. The default is always ascending. Each key given in the on phrase can 
be optionally modified to be. 

key.descending 

which will cause that key to be sorted in descending order. For completeness, ascending can 
be specified after the colon (':'), although this is unnecessary since it is the default. Descend¬ 
ing can be abbreviated by a single ‘d’ and, correspondingly, ascending can be abreviated by a 
single 'a'. 

hllldeior specifies (he percentage (from 1 to 100) of each primary data page that should be filled 
with tuples, under ideal conditions, hllldeior may be used with isam. cisam. hash and chash. 
( are should be taken when using large lillfactors since a non-uniform distribution of key values 
could cause overflow pages to be created, and thus degrade access performance for the relation 

A/w/x/.cw specifies the minimum number of primary pages a hash or chash relation must have 
Uuvpuvcv specifies the maximum number of primary pages a hash or chash relation may have 
Mtn/'d.ves and wf/.v/x/.erv must be at least one If both ininpages and maxpages arc specified m a 
modify, ininpages cannot exceed maxpagvs. 

Default values for fillfactor. ininpages. and maxpages are as follows: 



MODIFY (Ql hi ) 


2/23/79 


MODIFY (QUF.L ) 



/■//./ / l( 1 OR 

MIS PAGES 

MAX RAGES 

hash 

<0 

10 

no limn 

chash 

7s 

1 

no limit 

isam 

80 

NA 

NA 

cisam 

100 

NA 

NA 


IWMPl.F.S 

I* modify the emp relation to an indexed 
sequential storage structure with 
"name" as the keyed domain */ 

modify emp to isum on name 

I* if "name" is the first domain of the emp relation, 
the same result can be achieved by */ 

modify emp to tsam 

I" do the same modify but request a 60% occupancy 
on all primary pages V 

modify emp to isam on name where fillfactor = 60 

/' modify the supply relation to compressed hash 
storage structure with "num" and "quan” 
as keyed domains */ 

modify supply to chash on num. quan 

/* now the same modify but also request 75"/.. occupancy 
on all primary, a minimum of 7 primary pages 
pages and a maximum of 43 primary pages */ 

modify supply to chash on num, quan 

where fillfactor = 75, minpages = 7. 
maxpages = 43 

/* again the same modify but only request a minimum 
of 16 primary pages */ 

modify supply to chash on num, quan 
where minpages = 16 

/* modify parts to a heap storage structure */ 

modtfy parts to heap 

/* modify parts to a heap again, but have tuples 

sorted on "pnum" domain and have any duplicate 
tuples removed V 

modify parts to heapsort on pnum 

/* modify employee in ascending order by manager, 
descending order by salary and have am 
duplicate tuples removed */ 

modify employee to heapsort on manager, salary descending 


t F M SO 

sysmodlunix) 





MONITOR (QUEL ) 


2/23/79 


MONITOR (QUEL ) 


NAME 

monitor — interactive terminal monitor 
DESCRIPTION 

The interactive terminal monitor is the primary front end to Ingres. It provides the ability to 
formulate a query and review it before issuing it to Ingres. If changes must be made, one of 
the l MX text editors may be called to edit the query buffer. 

Messages and Prompts. 

The terminal monitor gives a variety of messages to keep the user informed of the status of the 
monitor and the query buffer 

As the user logs in, a login message is printed. This typically tells the version number and the 
login time. It is followed by the dayfile, which gives information pertinant to users. 

When INGRES is ready to accept input, the message "go" is printed. This means that the query 
buffer is empty. The message "continue" means that there is information in the query buffer. 
After a \go command the query buffer is automatically cleared il another query is typed in. un¬ 
less a command which affects the query buffer is typed first. These commands are \append. 
\edit. \print. \list, \eval, and \go For example, typing 
help parts 
\go 

print parts 

results in the query buffer containing 

print parts 

whereas 

help parts 
\go 
\prini 
print parts 

results in the query buffer containing 
help parts 
print parts 

An asterisk is printed at the beginning of each line when the monitor is waiting for the user to 
type input. 

Commands 

There are a number of commands which may be entered by the user to affect the query buffer 
or the user's environment. They are all preceeded by a backslash ("\"), and all are executed 
immediately (rather than at execution time like queries). 

Some commands may take a filename, which is defined as the first significant character after the 
end of the command until the end of the line. These commands may have no other commands 
on the line with them. Commands which do not take a filename may be slacked on the line; 
for example 

\dale\go\datc 

will give the time before and after execution of the current query buffer. 

\r 

\reset Erase the entire query (reset the query buffer). The former contents of the buffer 
are irretrieveably lost. 

\P 

\print Print the current query. The contents of the buffer are printed on the user s termi¬ 
nal. 

\l 

Mist Print the current query as it will appear after macro processing. Any side effects ol 

macro processing, such as macro definition, will occur. 




MONITOR < yi!HL I 


2 / 23/79 


MONITOR (QUEL ) 


exal Macro process the query butler anil replace the query butler with the result This is 
just like Mist except that the output is put into the query butler instead of to the ter¬ 
minal 

\e 

\cd 

\edit 

\cditor Enter the t nix text editor (see ED in the i nix Programmer's Manual); use the ED 
command 'w' followed by 'q' to return to the ingrls monitor. If .. filename is 
given, the editor is called with that file instead of the query buffer If the macro 
"[editorj" is defined, that macro is used as the pathname of an editor, otherwise 
“/bin/ed" is used It is important that you do not use the ”e" command inside the 
editor; if you do the (obscure) name of the query buffer will be forgotten 

\g 

\go Process the current query. The contents of the buffer are macro processed, 

transmitted to INGRI s, and run. 

\il 

\append Append to the query buffer. Typing \a after completion of a query will override ihe 
auto-clear feature and guarantees that the query buffer will not be reset 

\time 

\date Print out the current lime of day. 

\s 

\sh 

\shell Escape to the t Nix shell. Typing a control-d will cause you to exit the shell and re¬ 
turn to the iNCiRt s monitor, if there is a filename specified, that filename is taken as 
a shell file which is run with the query buffer as the parameter "$1”. If no filename 
is given, an interactive shell is forked. If the macro "{shell}” is defined, it is used 
as the pathname of a shell; otherwise, “/bin/sh” is used. 

\q 

\quit Exit from ingris. 

\cd 

\chdir Change the working directory of the monitor to the named directory. 

\i 

\ include 

\rcad Switch input to the named file. Backslash characters in the file will be processed as 
read. 

\w 

\writc Write the contents of the query buffer to the named tile. 

\branch Transfer control within a \include file. See the section on branching below 

\mark Set a label for \branch. 

\<auy other character> 

Ignore any possible special meaning of character following ‘ ' This allows the ' to 
be input as a literal character (See also qucl(qucl) - strings). It is important to 
note that backslash escapes are sometimes eaten up by the macro processor also; in 
general, send two backslashes if you want a backslash sent (even this is too simplis¬ 
tic [sighl — try to avoid using backslashes at .ill) 

Macros 

i or simplicity, the macros arc described in the section niacroslquel>. 

Branching 

Ihe branch and .mark commands permit arbitrary branching within a include tile (similar to 
the goto" and commands in the shell), \mark should be followed with a label branch 









MONITOR (QUEL I 


2 / 23/79 


MONITOR (QUEL) 


should ho followed with either a label, indicating unconditional branch, or an expression pro¬ 
ceeded b> a question mark, followed b> a label, indicating a conditional branch The branch is 
taken if the expression is greater than zero I or example, 

\branch Mtuplecounil < =0 notups 

branches to label "notups" if the "(tuplecountl" macro is less than or equal to zero 

The expressions usable in \branch statements are somewhat restricted The operators + . •. 

/, < =. >=, <. >. =, and != are all defined in the expected way. The left unary operator 
“!” can be used as to indicate logical negation There may be no spaces in the expression, 
since a space terminates the expression. 

Initialization 

At initialization (login) time a number of initializations lake place first, a macro called "{path¬ 
name}" is defined which expands to the pathname of the ist.kts subtree (normally 
"/mnt/ingres"); it is used by system routines such as demodb Second, the initialization file 
.../files/startup is read. This tile is intended to define system-dependent parameters, such as 
the default editor and shell Third, a user dependent initialization file, specified by a field in 
the users file, is read and executed. This is normally set to the file " mgres" in the user's 
home directory. The startup tile might be used to define certain macros, execute common 
range statements, and soforth Finally, control is turned over to the user's terminal 

An interrupt while executing either of the initialization files restarts execution of that step. 

Flags 

Certain flags may be included on the command line to INgris which affect the operation of the 
terminal monitor. The -a flag disables the auloclear function. This means that the query 
buffer will never be automatically cleared: equivalently, it is as though a \append command 
were inserted after every \go. Note that this means that the user must explicitly clear the query 
buffer using \reset after every query. The -d flag turns off the printing of the dayfile. The -s 
flag turns oft' printing of all messages (except errors) from the monitor, including the login and 
logout messages, the dayfile, and prompts. It is used for executing "canned queries", that is. 
queries redirected from files. 

M l M.SO 

ingres(unix), queKquel). mucros(quel) 


1)1 U.NOSTK S 

go 

continue 

Executing 

> >ed 

> >sh 


You may begin a fresh query. 

The previous query is finished and you are back in the monitor. 
The query is being processed by Ingres. 

You have entered the UNIX text editor. 

You have escaped to the UNIX shell. 


Funny character nnn converted to blank 

INGRES maps non-printing ASCII characters into blanks; this message in¬ 
dicates that one such conversion has just been made. 


IM (>\1P\TIBH.I TIES 

Note that the construct 

\rprint parts 

(intended to reset the query buffer and then enter "print parts") no longer works, since "rprint" 
appears to be one word. 





PRINT (QU» L ) 


1 / 26/79 


PRINT (QUIT.) 


\ \MK 

print - print relation(s) 
s\ Mil'sts 

print relname !. relname! 


IUM RUM ION 

Pnm displays the contents of each relation specified on the terminal (standard output). The 
formats for various types of domains can be defined by the use of switches when //teres is in¬ 
voked. Domain names are truncated to lit into the specified width. 

To print a relation one must either be the owner of the relation, or the relation must have "re¬ 
trieve to all" or "all to all" permissions. 

See ingres(quel) for details. 


KWMPLK 

/* Print the emp relation *7 
print emp 
print emp, parts 


SKK \l.so 

permit(quel), retrieve(quel), ingres(unix), printr(unix) handle long lines of output correctly — 
no wrap around. 

Print should have more formating features to make printouts more readable. 

Print should have an option to print on the line printer. 




PERMIT! QUEL > 


2/7/79 


PERMIT (QUEL > 


NAME 

permit — add permissions to a relation 

s\ NOPSIS 

define permit oplisl ! on i of | to | var l (atllist) i 
to name I at term | [ front time to time I 
I on day to day I | where qual 1 


DESCRIPTION 

The permit statement extends the current permissions on the relation specified by utr. Oplist is 
a comma separated list of possible operations, which can he retrieve, replace, delete, append, 
or all; all is a special case meaning all permissions. Same is the login name of a user or the 
word all Term is a terminal name of the form “uy.v' or the keyword all; omitting this phrase is 
equivalent to specifying all rum's are of the form hh:mm' on a twenty-four hour clock which 
limit the times of the day during which this permission applies. Pays are three-character abbre¬ 
viations for days of the week. The qual is appended to the qualification of the query when it is 
run 

Separate parts of a single permit statement are conjoined (ANDed). Different [lenmi statements 
are disjoined (ORed). for example, if you include 

... to erie at tty4 . . . 

the permit applies only to eric when logged in on tty4, but if you include two permit statements 

... to eric at all . . . 

. to all at tty4 . . 

then when eric logs in on tty4 he will get the union of the permissions specified by the two 
statements. If eric logs in on ttyd he will get only the permissions specified in the first permit 
statement, and if bob logs in on tty4 he will get only the permissions specified in the second 
permit statment. 

The permit statement may only be issued by the owner of the relation. Although a user other 
than the DBA may issue a permit statement, it is useless because noone else can access her rela¬ 
tions anyway. 

Pci mu statements do not apply to the owner of a relation or to views 

The statements 

define permit all on x to all 
define permit retrieve of x to all 

with no further qualification are handled as special cases and are thus particularly efficient. 
EXAMPLES 

range of e is employee 

define permit retrieve of e (name, sail to marc 
at ttyd from 8 00 to 1700 
on Mon to Eri 
where e mgr = "marc" 

range of p is parts 

define permit retrieve of e to all 


si t \i so 

destroy (quel) 







gi el<quel) 


2 / 23/79 


QUEL(QUEL > 


quel QLEry Language lor IM«KI s 
lit >( RUM ION 

The following is a description of the general syntax of yi it. Individual yt it statements and 
commands are treated separate!} in the document, this section describes the syntactic classes 
from which the constituent parts of yt 1 1 statements are drawn. 

1 Comments 

A comment is an arbitrary sequence of characters hounded on the left by "/•" and on the right 
by •■./" 

/* This is a comment »/ 

2 Names 

Names in yt 11 are sequences of no more than 12 alphanumeric characters, starting with an al¬ 
phabetic Underscore ( _) is considered an alphabetic. All upper —case alphabeties appearing 
anywhere except in strings are automatically and silently mapped into their lower-case coun¬ 
terparts. 

3. Keywords 

The following identifiers are reserved for use as keywords and may not be used otherwise: 


abs 

all 

and 

any 

append 

ascii 

at 

atari 

avg 

avgu 

by 

concat 

copy 

cos 

count 

countu 

create 

define 

delete 

destrov 

exp 

Hoat4 

float H 

from 

gamma 

help 

in 

index 

inti 

int2 

int4 

integrity 

into 

is 

log 

max 

min 

mod 

modify 

not 

of 

on 

onto 

or 

permit 

print 

range 

replace 

retrieve 

save 

sin 

sqrt 

sum 

sumu 

to 

unique 

until 

view 

where 



4 C onstants 

1 here are three types of constants, corresponding to the three data types available in yt I i for 
data storage. 

4 1 String constants 

Strings m yt 11 are sequences of no more than 255 arbitrary ASCII characters bounder) by dou¬ 
ble quotes ( " " I Upper case alphabeties within strings are accepted literally \lso. in order to 
imbed quotes within strings, it is necessary to prefix them with ' The same convention ap¬ 
plies ti> ’V itself. 

Only printing characters arc allowed within smugs Non-printing characters ti e control charac¬ 
ters! arc converted to blanks. 


-i 








yrtuyui i > 


2/23/7S) 


QUFLIQUKL) 


4 2 Integer constants 

Integer constants in (jt 1 1 range from -2,147.483.647 to +2.147.483.647. Integer constants 
beyond that range will be converted to floating point. II the integer is greater than 32,767 or 
less than -32.767 then it will be left as a two byte integer. Otherwise it is convened to a four 
byte integer. 

4 3. Floating point constants 

Floating constants consist of an integer part, a decimal point, and a fraction part or scientific 
notation of the following format: 

1 < dig, >) |. <dig>] le|H l+|-| ! < dig > 11 

Where <dig> is a digit, (I represents zero or one. lj represents zero or more, and | represents 
alternation An exponent with a missing mantissa has a mantissa of I inserted There may be 
no extra characters embedded in the string. Floating constants arc taken to be double-precision 
quantities with a range of approximately -I0 !l ' to 10 ,s and a precision of 17 decimal digits 

5. Attributes 

An attribute is a construction of the form: 
variable.domain 

l'ariaMe identifies a particular relation and can be thought of as standing for the rows or tuples 
of that relation. A variable is associated with a relation by means of a kiiikc statement. Domain 
is the name of one of the columns of the relation over which the variable ranges. Together 
they make up an attribute, which represents values of the named domain. 

6. Arithmetic operators 

Arithmetic operators lake numeric type expressions as operands. Unary operators group right 
to left; binary operators group left to right. The operators (in order of descending precedence! 
are: 

+ ,- (unary) plus, minus 

** exponentiation 

♦ ./ multiplication, division 

+ .-- (binary) addition, subtraction 

Parentheses may be used for arbitrary grouping. Arithmetic overflow and divide by zero are 
not checked on integer operations. Floating point operations are checked for overflow, 
underflow, and divide by zero only if (he appropriate machine hardware exists and has been en¬ 
abled. 

7. Fxpressions (a expr) 

An expression is one of the following: 

constant 

attribute 

functional expression 
aggregate or aggregate function 

a combination of numeric expressions and arithmetic operators 

For the purposes of this document, an arbitrary expression will be refered to by the name 
a cv/v. 

8 formats 

I very a c\pi has a format denoted by a letter (c, i. or f. for character, integer, or floating data 
types respectively) and a number indicating the number of bytes of storage occupied Formats 
currently supported are listed below The ranges of numeric types arc indicated in parentheses 





QlJFl. (QUIT. ) 


2/23/79 


Q11KL(QUBL) 


cl 

11 

12 

i4 

t'4 

14 


c255 


character data of length 1 -255 characters 

1- byte integer ( 128 to 4 127) 

2- h\te integer ( 32768 to +32767) 

4-hyte integer (-2,147.483,648 to +2.147,483,647) 

4-byte lloating ( -10 ,K to + 10 ls , 7 decimal digit precision) 
8-byte floating (-lO'* to + 10 IK . 17 decimal digit precision) 


One numeric format can be converted to or substituted for any other numeric format. 


9. Type Conversion. 

When operating on two numeric domains of different types. iNtiRt.s converts as necessary to 
make the types identical. 

When operating on an integer and a floating point number, the integer is converted to a floating 
point number before the operation. When operating on two integers of different sizes, the 
smaller is converted to the size of the larger. When operating on two floating point number of 
different size, the larger is converted to the smaller. 

The following table summarizes the possible combinations. 



il 

i2 

i4 

i'4 

f8 

il - 

il 

i2 

i4 

f4 

f8 

i2 - 

i2 

i2 

i4 

f4 

f8 

i4 - 

i4 

i4 

i4 

f4 

f8 

f4 - 

14 

f4 

f4 

f4 

f4 

f8 - 

f8 

l'8 

(8 

f4 

f8 


iNtiKts provides five type conversion operators specifically for overriding the default actions. 
The operators are: 


inti (aexpr) 
int2(a expr) 
int4(a_expr) 
float4(a_expr) 
ffoat8(a_expr) 


result type il 
result type i2 
result type i4 
result type f4 
result type 18 


The type conversion operators convert their argument a expr to the requested type. A expr can 
be anything including character. If a character value cannot be converted, an error oecures and 
processing is halted This can happen only if the syntax of the character value is incorrect. 

Overflow is not checked on conversion. 

10. Target list 

A target list is a parenthesized, comma separated list of one or more elements , each of which 
must be of one of the following forms: 

a) result minium- is a expr 

Result annum' is the name of the attribute to be created (or an already existing attribute name 
in the case of update statements.) The equal sign (" = ") may be used interchangeably with is. 
In the case where a expr is anything other than a single attribute, this form must be used to as¬ 
sign a result name to the expression 

h> attribute 

In the case of a retrieve, the resultant domain will acquire the same name as that of the attribute 
being retrieved. In the case of update statements ( append, replan ), the relation being updated 
must have a domain with exactly that name. 

Inside the target list the keyword all can he used to represent all domains. I or example 

range of e is employee 

retrieve (c all) where e.salary > 10000 








QUEL(QUEL) 


2/23/79 


QUEL(QUEL) 


will retrieve all domains of employee lor those tuples which satisfy the qualification. All cun be 
used in the target list of a retrieve or an append. The domains will be inserted in their "create" 
order, that is, the same order they were listed in the create statement 

11 Comparison operators 

Comparison operators take arbitrary expressions as operands. 

< (less than) 

<= (less than or equal) 

> (greater than) 

> = (greater than or equal) 

= (equal to) 

!= (not equal to) 

They are all of equal precedence. When comparisons are made on character attributes, all 
blanks are ignored. 

12. Logical operators 

Logical operators take clauses as operands and group left-to-right: 

not (logical not; negation) 

and (logical and; conjunction) 

or (logical or; disjunction) 

Not has the highest precedence of the three. And and or have equal precedence Parentheses 
may be used for arbitrary grouping. 

13 Qualification (qual) 

A qualification consists of any number of clauses connected by logical operators. A clause is a 
pair of expressions connected by a comparison operator. 

a expr comparisonoperator a expr 

Parentheses may be used for arbitrary grouping. A qualification may thus be: 

clause 

not qual 
qual or qual 
qual and qual 
( qual ) 

14. Functional expressions 

A functional expression consists of a function name followed by a parenthesized (list of) 
operand(s). Functional expressions can be nested to any level. In the following list of func¬ 
tions supported ( n) represents an arbitrary numeric type expression. The format of the result is 


indicated on the right. 

abs (n) - 

same as u (absolute value) 

ascii (n) — 

character siring (converts numeric to character) 

atan(/>) - 

18 (arctangent) 

concat(u.b) - 

character (character concatenation. See 16.2) 

cos(») — 

('8 (cosine) 

exp(w) — 

18 (exponential of /;) 

xamma(n) - 

18 (log gamma) 

IngOi) — 

f8 (natural logarithm) 

mod(n./>) — 

same as bin modulo b. n and h must be il. i2. or i4) 

sin(/f) — 

18 (sine) 

sqrt( it) - 

f8 (square root) 


IS. Aggregate expressions 

Aggregate expressions provide a way to aggregate a computed expression over a set of tuples 


- 4 - 





Ql EL (QUID 


2/23/79 


QUEL(QUEL) 


15 1. Aggregation operators 

The definitions of the aggregates are listed below 


count - 

(i4) count of occurrences 

countu — 

(i4) count of unique occurrences 

sum — 

summation 

SUIllU — 

summation of unique values 

avg - 

(f8) average (sum/count) 

avgu - 

(l‘8) unique average (sumu/eouniu) 

max - 

maximum 

min — 

minimum 

any - 

<i2) value is 1 if any tuples satisfy the qualification, else it is 0 


15.2. .simple aggregate 

aggregationjiperator ( a_e\pr 1 where i/ual] ) 

A simple aggregate evaluates to a single scalar value. Acxpr is aggregated over the set of tu¬ 
ples satisfying the qualification (or all tuples in the range of the expression if no qualification is 
present). Operators sum and avg require numeric type acxpr; count, any. max and nun permit a 
character type attribute as well as numeric type a cxpr. 

Simple aggregates are completely local. That is, they are logically removed from the query, pro¬ 
cessed separately, and replaced by their scalar value. 

15.3. "any" aggregate 

It is sometimes useful to know if any tuples satisfy a particular qualification. One way of doing 
this is by using the aggregate count and checking whether the return is zero or non-zero. Using 
any instead of count is more efficient since processing is stopped, if possible, the first time a tu¬ 
ple satisfies a qualification. 

Any returns 1 if the qualification is true and 0 otherwise. 

15.4. Aggregate functions 

aggregation opera tor (a_expr by byjloniam 
j, byjloniam} [ where qua !) ) 

Aggregate functions are extensions of simple aggregates. The bv operator groups (i.e. parti¬ 
tions) the set of qualifying tuples by by domain values. For more than one by domain, the 
values which are grouped by arc the concatenation of individual by domain values. A expr is as 
in simple aggregates. The aggregate function evaluates to a set of aggregate results, one for 
each partition into which the set of qualifying tuples has been grouped. The aggregate value 
used during evaluation of the query is the value associated with the partition into which the tu¬ 
ple currently being processed would fall. 

Unlike simple aggregates, aggregate functions are not completely local. The hy lnt. which 
differentiates aggregate functions from simple aggregates, is global to the query. Domains in 
the by list are automatically linked to the other domains in the query which are in the same re¬ 
lation. 

Example: 

/• retrieve tile average salary for the employees 
working for each manager •/ 
range of e is employee 

retrieve (e.manager. avesal = avg(e.salary by e. manager)) 

15 5 Aggregates on Unique Values. 

It is occasionally necessary to aggregate on unique values of an expression. I he avgu. \umu. 
and ( oiintn aggregates all remove duplicate values before performing the aggregation lor ex¬ 
ample: 


- 5 - 




QUEL(QUEL) 


2/23/79 


QUEL < QUEL) 


counitc. manager) 

would tell >ou how many occurrences of t .manager cx ist. But 
countu<e. manager) 

would tell you how many unique values of e. manager cx ist. 

16. Special character operators 

There are three special features which are particular to character domains. 

16.1 Pattern matching characters 

There are four characters which take on special meaning when used in character constants 
(strings): 

* matches any string of zero or more characters. 

? matches any single character. 

[..I matches any of characters in the brackets. 

These characters can be used in any combination to form a variety of tests. For example 

where e.name = — matches any name. 

where e.name = "E*" - matches any name starting with "E”. 

where e.name = "*ein'' — matches all names ending with "ein" 

where e.name = Maeioul*" — matches any name with at least one vowel. 

where e.name = "Allman?" - matches any seven character name starting with "Allman". 

where e.name = "(A—J]»" — matches any name starting with A,B,...J. 

The special meaning of the pattern matching characters can be disabled by preceding them with 
a "\". Thus 'V refers to the character When the special characters appear in the target list 
they must be escaped. For example: 

title = "\*\*\* ingres \*\*\»" 

is the correct way to assign the string "*•* ingres ***" to the domain "title". 

16.2 Concatenation 

There is a concatenation operator which can form one character string from two. Its syntax is 
"concat(fieldl, field2)". The size of the new character siring is the sum of the sizes of the origi¬ 
nal two. Trailing blanks are trimmed from the first field, the second field is concatenated and 
the remainder is blank padded. The result is never trimmed to 0 length, however. Concat can 
be arbitrarily nested inside other concats. For example: 

name — concat(concat(x.lastname, ","), x.firstname) 
will concatenate x.lastname with a comma and then concatenate x.firstname to that. 

16.3 Ascii (numeric to character translation) 

The ascii function can be used to convert a numeric field to its character representation. This 
can be useful when it is desired to compare a numeric value with a character value. For exam¬ 
ple: 

retrieve ( ... ) 

where x.chardomain = ascii(x.numdomain) 

Ascn can be applied to a character value. The result is simply the character value unchanged. 
The numeric conversion formats arc determined by the printing formats (see ingres(unix)). 

sir xt.so 

append(quel). delete(quel), range(quel). rcplacc(quel). rctrievc(qucl). ingres(unix) 


BU.S 

The maximum number of variables which can appear in one query is 10. 



QLEL(QUEL) 


2/23/79 


QUEL(QUEL) 


Numeric overflow, underflow, and divide by zero are not detected. 
When converting between numeric types, overflow is not checked. 


- 7 - 


RANGE(QUEL) 


2/29/79 


RANGE(QUEL) 


WMF 

range — declare a variable to range over a relation 
S\ NOPSIS 

range of variable is relname 
DESCRIPTION 

Range is used to declare variables which will be used in subsequent quel statements. The vari¬ 
able is associated with the relation specified by relname. When the variable is used in subse¬ 
quent statements it will refer to a tuple in the named relation. A range declaration remains in 
effect for an entire INGRES session (until exit from INGRES), until the variable is redeclared by a 
subsequent range statement, or until the relation is removed with the destroy command. 

EXAMPLE 

/* Declare tuple variable e to range over relation emp »/ 
range of e is emp 


SEE ALSO 

quel(quel), destroy(quel) 


BIGS 

Only 10 variable declarations may be in effect at any time. After the 10th range statement, the 
least recently referenced variable is re —used for the next range statement. 




I 


REPl AC E(QUEL) 


2/29/79 


REPLACE(QUEL) 


\ \Mt 

replace — replace values of domains in a relation 
M NOHSIS 

replace tuple variable <target list) (where qual) 

UKSl RIPTION 

Replace changes the values of the domains specified in the tarpeijisi for all tuples which satisfy 
the qualification qual The tuple variable must have been declared to range over the relation 
which is to be modified. Note that a tuple variable is required and not the relation name. Only 
domains which are to be modified need appear in the tarpet hst. These domains must be 
specified as result attnames in the larpei ji^t either explicitly or by default (see quel (quel)). 

Numeric domains may be replaced by values of any numeric type (with the exception noted 
below). Replacement values will be converted to the type of the result domain. 

Only the owner of a relation, or a user with replace pemission on the relation can do replace. 

If the tuple update would violate an integrity constraint (see integrity (quel) >, it is not done. 

EXAMPLE 

/* Give all employees who work for Smith a 10% raise «/ 
range of e is emp 

replace e(sal = 1.1 * e.sal) where e.mgr = "Smith" 

NEE ALSO 

integrity(quel), permit(quel), quel(quel), range(quel) 

otvciNosrics 

Use of a numeric type expression to replace a character type domain or vice versa will produce 
diagnostics. 




RETRIES! (QUEL) 


2/29/79 


RETRIEVE (QUEL ) 


reiricve - reirieve tuples from a relation 
ss NOPSIS 

retrieve ilinto] relname) (target list) (where qua)] 
retrieve unique (target list) (where quail 

description 

Retrieve will get all tuples which satisfy the qualification and either display them on the terminal 
(standard output) or store them in a new relation. 

If a relname is specified, the result of the query will be stored in a new relation with the indi¬ 
cated name. A relation with this name owned by the user must not already exist. The current 
user will be the owner of the new relation The relation will have domain names as specified in 
the targetJist result attnames. The new relation will be saved on the system for seven (7) days 
unless explicitly saved by the user until a later date. 

If the keyword unique is present, tuples will be sorted on the first domain, and duplicates will 
be removed, before being displayed. 

The keyword all can be used when it is desired to retrieve all domains 

If no result relname is specified then the result of the query will be displayed on the terminal 
and will not be saved. Duplicate tuples are not removed when the result is displayed on the 
terminal. 

The formal in which domains arc printed can be defined at the time ingres is invoked (see 
ingres(unix)). 

If a result relation is specified then the default procedure is to modify the result relation to an 
cheapsort storage structure removing duplicate tuples in the process. 

If the default cheapsort structure is not desired, the user can override this at the time ingris is 
invoked by using the -r switch (see ingres(unix)). 

Only the relation’s owner and users with retrieve permission may retrieve from it. 

E\ XMPI.E 

/* Find all employees who make more than their manager */ 
range of e is emp 
range of m is emp 

retrieve (e.name) where e.mgr = m.name 
and e.sal > m.sal 

/* Retrieve all domains for those who make more 
than the average salary */ 
retrieve into temp (c all) where e.sal > avg(c.sal) 

/* retrieve employees’s names sorted */ 
retrieve unique (e.name) 

>rt w.so 

modify (quel), permit(quel). quel(quel). rangc(quel), save(qucl), ingrcs(umx) 

PI \(t\OS I it s 


Ht t.s 






SAM <CH H > 


.V10/77 


savi: <uui-:l > 


S \Ml 

save - ->.i\e a relation until ,t date. 

NOPSIS 

sate relname until month day year 
orst rii*i ion 

Suw in used to keep relations beyond the del'auit 7 day life span. 

Month can be an integer from I through 12. or the name of the month, either abbreviated or 
spelled out 

Only the owner of a relation can sine that relation. There is an inghi s process which typically 
removes a relation immediately after ns expiration date has passed. 

The actual program which destroys relations is called purge. It is not automatically run. It is a 
local decision when expired relations are removed. 

System relations have no expiration date. 

KMMPl.i: 

I* Save the emp relation until the end of February 1987 */ 
save emp until feb 28 1987 

si r vt.so 

create(quel), retrieve(quel), purge(unix) 







m 


VIEW (QI.J I-L ) 


2/7/79 


VIEW (QUEL) 


\ Wll 

view - define a virtual relation 
SV NOPSIS 

define view name (target-list) [ where qual 1 
DISC RIPTION 

The syntax of the new statement is almost identical to the retrieve into sluiment; however, the 
data is not retrieved. Instead, the definition is stored. When the relation name is later used, 
the query is converted to operate on the relations specified in the target-list. 

All forms of retrieval on the view are fully supported, but only a limited set of updates are sup¬ 
ported because of anomolies which can appear. Almost no updates are supported on views 
which span more than one relation. No updates are supported that affect a domain in the 
qualification of the view or that affect a domain which does not translate into a simple attribute. 

In general, updates are supported if and only if it can be guaranteed (without looking at the ac¬ 
tual data) that the result of updating the view is identical to that of updating the corresponding 
real relation. 

The person who defines a view must own all relations upon which the view is based. 

EXAMPLE 

range of e is employee 
range of d is dept 

define view empdpt (ename = e.name. c.sal, dname = d.name) 
where e.mgr = d.mgr 


SEE Vl.SU 

retrieve(quel), destroy (quel) 





COPYDB (UNIX) 


3/14/79 


COPYDB (UNIX) 


name 

copydb — create batch files to copy out a data base and restore it. 
sy NOPS1S 

copydb ( —uname ] database full-path-name-of-direciory I relation ... ) 

DESCRIPTION 

Copydb creates two INGRES command files in the directory: Copy.out, which contains Quel in- 
stuctions which will copy all relations owned by the user into files in the named directory, and 
copy.in, which contains instructions to copy the files into relations, create indexes and do 
modifies. The files will have the same names as the relations with the users INGRES id tacked 
on the end. (The directory MUST NOT be the same as the data base directory as the files have 
the same names as the relation files.) The — u flag may be used to run copydb with a different 
user id. (The fact that copydb creates the copy files does not imply that the user can necessarily 
access the specified relation). If relation names are specified only those relations will be includ¬ 
ed in the copy files. 

Copydb is written in Equel and will access the database in the usual manner. It does not have 
to run as the INGRES user. 


EXAMPLE 

chdir /mnt/mydir 

copydb db /mnt/mydir/backup 

Ingres db < backup/copy.out 

tp rl backup 

rm — r backup 

tp xl 

ingres db < backup/copy.in 
DIAGNOSTIC'S 

Copydb will give self-explanatory diagnostics. If “too many indexes” is reported it means that 
more than ten indexes have been specified on one relation. The constant can be increased and 
the program recompiled. Other limits are set to the system limits. 


BIGS 

Copydb assumes that indexes which are ISAM do not need to be remodified. Copydb cannot tell 
if the relation was modified with a fillfactor or minpages specification. The copy .in file may be 
edited to reflect this. 




CREATDB (UNIX) 


3/14/79 


CREATDB (UNIX) 


NAME 

creatdb — create a data base 
SA NOPSIS 

creatdb 1 —u name 1 [ — e 1 ( — m 1 l ±c] ( ±q1 dbname 
DESCRIPTION 

Creatdb creates a new INGRES database, or modifies the status of an existing database. The per¬ 
son who executes this command becomes the Database Administrator (DBA) for the database. 
The DBA has special powers not granted to ordinary users. 

Dbname is the name of the database to be created. The name must be unique among all 
Ingres users. 

The flags ±c and ±q specify options on the database. The form +x turns an option on, while 
— x turns an option off. The —c flag turns off the concurrency control scheme (default on). 
The +q flag turns on query modification (default off). 

Concurrency control should not be turned off except on databases which are never accessed by 
more than one user. This applies even if users do not share data relations, since system rela¬ 
tions are still shared. If the concurrency control scheme is not installed in UNIX, or if the spe¬ 
cial file /dev/lock does not exist or is not accessible for read-write by INGRES, concurrency con¬ 
trol acts as though it is off (although it will suddenly come on when the lock driver is installed 
in UNIX). 

Query modification must be turned on for the protection, integrity, and view subsystems to 
work, however, the system will run slightly slower in some cases if it is turned on. It is possi¬ 
ble to turn query modification on if it is already off in an existing database, but it is not possible 
to turn it off if it is already on. 

Databases with query modification turned off create new relations with all access permitted for 
all users, instead of no access except to the owner, the default for databases with query 
modification enabled. 

Database options for an existing database may be modified by stating the — e flag. The database 
is adjusted to conform to the option flags. For example: 
creatdb —e +q mydb 

turns query modification on for database “mydb” (but leaves concurrency control alone). Only 
the database administrator (DBA) may use the —e flag. 

When query modification is turned on, new relations will be created with no access, but previ¬ 
ously created relations will still have all access to everyone. The destroy command may be used 
to remove this global permission, after which more selective permissions may be specified with 
the permit command. 

The INGRES user may use the —u flag to specify a different DBA. the flag should be immediate¬ 
ly followed by the login name of the user who should be the DBA. 

The —m flag specifies that the UNIX directory in which the database is to reside already exists. 
This should only be needed if the directory if a mounted file system, as might occur for a very 
large database. The directory must exist (as .../data/bas e/dbname), must be mode 777, and 
must be empty of all files. 

The user who executes this command must have the U_CREATDB bit set in the status field of 
her entry in the users file. 

The Ingres superuser can create a file in .../data/base containing a single line which is the full 
pathname of the location of the database. The file must be owned by Ingres and be mode 644. 
When the database is created, it will be created in the file named, rather than in the directory 
.../data/base. For example, if the file .../data/base/ericdb contained the line 
/mnt/eric/database 

then the database called “ericdb” would be physically stored in the directory 
/mnt/eric/database rather than in the directory .../data/base/ericdb. 




CREATDB (UNIX ) 


3/14/79 


CREATDB (UNIX) 


tUMPl.t 

creaidb demo 

ereatdb — ueric -q erics db 
creaidb — e +q — c — u:av erics db 


FILES 

.../files/dbtmplt6.2 

.../files/data/base/* 

.../files/datadir/* (for compatibility wiih previous versions) 

SEE ALSO 

demodb(unix), destroydb(unix). users(files). chmod(l). destroydb(quel), permit(quel) 
DIAGNOSTICS 

No database name specified. 

You have not specified the name of the database to create (or modify) with the com¬ 
mand. 

You may not access this database 

Your entry in the users file says you are not authorized to access this database. 

You are not a valid INGRES user 

You do not have a users file entry, and can not do anything with INGRES at all. 

You are not allowed this command 

The U CREATDB bit is not set in your users file entry. 

You may not use the -u flag 

Only the Ingres superuser may become someone else. 

<name> does not exist 

With —e or — m, the directory does not exist. 

<name> already exists 

Without either —e or —m, the database (actually, the directory) already exists. 
<name> is not empty 

With the —m flag, the directory you named must be empty. 

You are not the DBA for this database 

With the — e flag, you must be the database administrator. 








DESTROYDB (UNIX) 


3/14/79 


DESTROYDB (UNIX) 


NAME 

destroydb - destroy an existing daiabase 
SYNOPSIS 

destroydb ( — s 1 ( — m ] dbname 
DESCRIPTION 

Destroydb will remove all reference to an existing database. The directory of the database and 
all files in that directory will be removed. 

To execute this command the current user must be the database administrator for the database 
in question, or must be the INGRES superuser and have the — s flag stated. 

The —m flag causes destroydb not to remove the UNIX directory. This is useful when the direc¬ 
tory is a separate mounted Unix file system. 

EXAMPLE 

destroydb demo 
destroydb -s erics db 


FILES 

.../data/base/* 

.. /datadir/* (for compatibility with previous versions) 

SEE ALSO 

creatdb(unix) 

DIAGNOSTICS 

invalid dbname — the database name specified is not a valid name. 

you may not reference this database - the database may exist, but you do not have permission 
to do anything with it. 

you may not use the —s flag - you have tried to use the —s flag, but you are not the INGRES 
superuser. 

you are not the dba — someone else created this daiabase. 
database does not exist - this database does not exist. 





EQUEL ( UNIX) 


3/14/79 


EQUEL (UNIX ) 


VWIF. 

equel - Embedded QUEL interface to C 
sy noKis 

equel [ — d ] [ —f ] l — r ) file.q ... 

DESCRIPTION 

Equel provides the user with a method of interfacing the general purpose programming language 
“C" with Ingres. It consists of the equel. pre-compiler and the equel runtime library. 

Compilation 

The precompiler is invoked with the statement: 

equel (<flags>) filel.q 1 <flags>] file2.q ... 

where file/?.q are the source input file names, which must end with .q. The output is written to 
the file “filen.c”. As many files as wished may be specified. 

The flags that may be used are: 

—d Generate code to print source listing file name and line number when a run-time error oc¬ 
curs. This can be useful for debugging, but takes up process space. Defaults to off. 

—f Forces code to be on the same line in the output file as it is in the input file to ease inter¬ 
preting C diagnostic messages. EQUEL will usually try to get all C code lines in the output 
file on the same lines as they were in the input file. Sometimes it must break up queries 
into several lines to avoid C-preprocessor line overflows, possibly moving some C code 
ahead some lines. With the —f flag specified this will never happen and, though the line 
buffer may overflow, C lines will be on the right line. This is useful for finding the line in 
the source file that C error diagnostics on the output file refer to. 

— r Resets flags to default values. Used to supress other flags for some of the files in the ar¬ 
gument list. 

The output files may than be compiled using the C compiler: 
cc filel.c file2.c ... — Iq 

The — Iq requests the use of the EQUEL object library. 

All EQUEL routines and globals begin with the characters ‘'11”. and so all globals variables and 
procedure names of the form IIxva are reserved for use by EQUEL and should be avoided by 
equel users. 

Basic Syntax 

IQl El commands are indicated by lines which begin with a double pound sign (“##"). Other 
lines are simply copied as is. All normal INGRES commands may be used in EQl 11 and have the 
same effect as if invoked through the interactive terminal monitor. Only retrieve commands 
with no result relation specified have a different syntax and meaning. 

The format of retrieve without a result relation is modified to: 

## retrieve (C-variable = a fen 1 , C-variable = a fen ) ) 
optionally followed (immediately) b\ 

## ( w here qua I 1 

## i ' 

/• C'-code */ 

## ) 

I his statement causes the ‘‘('-code" to be executed once for each tuple rctrie\ed. with the 
• (-variable 's set appropriately. Numeric values of any type arc converted as necessary \o 
conversion is done between numeric and character values. (The normal ingkis asm f unction 
may be used for this purpose.) 







EQUEL ( UNIX) 


3/14/79 


EQUEL (UNIX) 


Also, the following equel commands are permitted. 

## ingres lingres flags] databasename 

This command starts Ingres running, and directs ail dynamically following queries 
to the database data base name. It is a run-time error to execute this command 
twice without an intervening "## exit”, as well as to issue queries while an “## 
ingres” statement is not in effect. Each flag should be enclosed in quotes to avoid 
confusion in the EQUEL parser: 

## ingres " — f4fl0.2" " — i2\2" demo 

## exit 

Exit simply exits from INGRES. It is equivalent to the \q command to the teletype 
monitor. 

Parametrized Quel Statements 

Quel statements with target lists may be “parametrized”. This is indicated by preceding the 
statement with the keyword “param". The target list of a parametrized statement has the form 

( tlvar, argv) 

where tl var is taken to be a string pointer at execution time (it may be a string constant) and 
interpreted as follows. For any parametrized equel statement except a retrieve without a result 
relation (no "into rel”) (i.e. append, copy, create, replace, retrieve into) the string tl var is tak¬ 
en to be a regular target list except that wherever a '%' appears a valid Ingres type (f4, f8, i2, 
i4, c) is expected to follow. Each of these is replaced by the value of the corresponding entry 
into argv (starting at 0) which is interpreted to be a pointer to a variable of the type indicated 
by the sequence. Neither argv nor the variables which it points to need be declared to EQl 
EL. For example. 

char *argv(10l; 

argv[0] = &double_var; 
argv[l] = &int_var; 

## param append to rel 

## ("doml = %f8, dom2 = %i2", argv) 

## /* to escape the "%<ingres_type>" mechanism use "%%" */ 

## /* This places a single '%’ in the string. */ 

On a retrieve to C-variables, within dvar, instead of the C-variable to retrieve into, the same 
escape sequences are used to denote the type of the corresponding argv entry into which 
the value will be retrieved. 

The qualification of any query may be replaced by a string valued variable, whose contents is 
interpreted at run time as the text of the qualification. 

The copy statement may also be parametrized. The form of the parametrized copy is analogous 
to the other parametrized statements: the target list may be parametrized in ihe same manner as 
the append statements, and furthermore, the froni/into keyword may be replaced by a string 
valued variable whose content at run time should be into or from. 

Declarations 

Any valid C variable declaration on a line beginning with a “##" declares a C-variable that 
may be used in an EQi'Ei statement and as a normal variable. All variables must be declared 
"before being used. Anywhere a constant may appear in an ingris command, a C-variable may 
appear. The value of the C-variable is substituted at execution time 

Neither nested structures nor variables of type char (as opposed to pointer to char or array of 
char) are allowed. Furthermore, there are two restrictions in the way variables arc referenced 
within equel statements. All variable usages must be dereferenced and/or subscripted (for ar¬ 
rays and pointers), or selected (for structure variables) to yield lvalues (scalar values). Chai 
variables are used by i quel as a means to use strings. Therefore when using a char array or 








EQUEL ( UNIX) 


3/14/79 


EQUEL (UNIX 1 


pointer it must be dereferenced only to a "char Also, variables may not have parentheses 

in their references. For example: 

## struct xxx 

## { 

int i; 

## int *ip; 

## ] *»struct_var; 

/* not allowed */ 

## delete p where p.ifield = »(*struct_var)->ip 
/* allowed */ 

## delete p where p.ifield = *struct_var[0)->ip 

C variables declared to EQUEL have either global or local scope. Their scope is local if their de¬ 
claration is within a free (not bound to a retrieve) block declared to EQUEL. For example. 

/• globals scope variable */ 

## int Gint; 

func(i) 
int i; 

## ( 

/* local scope variable »/ 

## int *gintp; 

## } 

If a variable of one of the char types is used almost anywhere in an EQUEL statement the con¬ 
tent of that variable is used at run time. For example: 

## char *dbnamelMAXDATABASES + H; 

int currentdb; 

dbnamelcurrent db] = "demo"; 

## ingres dbnamelcurrent db) 

will cause INGRES to be invoked with data base "demo''. However, if a variable’s name is to be 
used as a constant, then the non-referencing operator '#' should be used. For example: 

## char *demo. 

demo = "my database". 

/* ingres —d my database •/ 

## ingres " — d" demo 

N 

/* ingres —d demo */ 

## ingres ”-d" #demo 

The ( -preprocessor's #inelude feature may be used on files containing etiuel statements and 
declarations if these files are named uhyiIiiuk-H.U. An i Qtl i processed version of the tile, 
which will be #induded by the C-preproccssor. is left in anyihwi;. c.li. 

Errors and Interrupts 

IXgKI s and run time I qi 11 errors cause the routine Ilerror to be called, with the error nunihci 
and the parameters to the error in an array of string pointers as in a C language main routine 
1 he error message will be looked up and printed, before printing the error message, the routine 
<»llprmt crr>(> is culled wiili the error number that ocurred as us single argument The error 
message corresponding to the error number returned by <*llprini errfll will be printed I’rint- 
rng will be supressed it (•llprint err)() returns 0 llprint err may be reassigned to. and is use- 





EQUEL (UNIX) 


3 / 14/79 


EQUEL (UNIX ) 


ful for programs which map INGRES errors into their own error messages. In addition, if the 
d" flag was set the file name and line number of the error will be printed. The user may 
write an Ilerror routine to do other tasks as long as the setting of llerrflag is not modified as 
this is used to exit retrieves correctly. 

Interrupts are caught by equel if they are not being ignored. This insures that the rest of 
INGRES is in sync with the equel process. There is a function pointer, llinierrupt, which poinis 
to a function to call after the interrupt is caught. The user may use this to service the inierrupi 
It is initialized to "exitO" and is called with -1 as its argument. For example: 

extern ini (•llinierrupt)(); 
extern reset0; 

setexitO; 

llinierrupt = reset; 
mainloopO; 

To ignore interrupts, signal!) should be called before the ## ingres satatement is executed. 


files 

,../files/error6.2_« 

Can be used by the user to decipher INGRES error numbers. 

/lib/libq.a 

Run time library. 


SEE ALSO 

.../doc/other/equeltut.q, C reference manual, ingres(UNlX), quel(QUEL) 


BIGS 

The C-code embedded in the tuple-by-tuple retrieve operation may not contain additional 
QUEL statements or recursive invocations of INGRES. 

There is no way to specify an il format C-variable. 

Includes of an equel file within a parameterized target list, or within a C variable's array sub¬ 
scription brackets, isn’t done correctly. 












HELPR ( UNIX) 


3/14/79 


HELPR (UNIX) 


NAME 

helpr - get information about a database. 

SN VoPsts 

helpr [ — u name] l ±w ] database relation ... 


DESCRIPTION 

Helpr gives information about the named relation(s) out of the database specified, exactly like 
the help command. 

Flags accepted are — u and ±u. Their meanings are identical to the meanings of the same flags 
in INGRES. 


SEE ALSO 

ingres(unix), help(quel) 

DIAGNOSTIC'S 

bad flag — you have specified a flag which is not legal or is in bad format, 
you may not access database — this database is prohibited to you based on status information in 
the users file. 

cannot access database — the database does not exist. 


- I - 




INGRES (UNIX) 


3/14/79 


INGRES (UNIX) 


NAME 

ingres — ingres relational data base management system 
SYNOPSIS 

ingres l flags ] dbname ( process table 1 

DESCRIPTION 

This is the UNIX command which is used to invoke INGRES. Dbname is the name of an existing 
data base. The optional flags have the following meanings (a “±” means the flag may be stal¬ 
ed “+.v” to set option cor “ —,v” to clear option x. “ —” alone means that “ —.v” must be 
stated to get the v function) 

±U Enable/disable direct update of the system relations and secondary indicies You 

must have the 000004 bit in the status field of the users file set for this flag to be ac¬ 

cepted. This option is provided for system debugging and is strongly discouraged for 
normal use. 

— u name Pretend you are the user with login name name (found in the users file). If name is 

of the form :.v.v. .v.x is the two character user code of a user. This may only be used 
by the DBA for the database or by the INGRES superuser. 

— C/V Set the minimum field width for printing character domains to A. The default is 6. 

— i/A Set integer output field width to A'. / may be 1, 2, or 4 for il’s, i2's, or i4's repec- 

tively. 

— fixM.N Set floating point output field w idth to M characters with A'decimal places. / may be 

4 or 8 to apply to 1'4’s or f8's respectively. ,v may be e. E, f, F. g, G, n, or N to 
specify an output format. E is exponential form, F is floating point form, and G and 
N are identical to F unless the number is too big to fit in that field, when it is output 
in E format. G format guarantees decimal point alignment; N does not. The de¬ 
fault format for both is nl0.3. 

— v.V Set the column seperator for retrieves to the terminal and print commands to be ,V. 

The default is vertical bar. 

— r M Set modify mode on the retrieve command to M. M may be isam, cisam, hash, 

chash, heap, cheap, heapsort, or cheapsort, for ISAM, compressed ISAM, hash 
table, compressed hash table, heap, compressed heap, sorted heap, or compressed 
sorted heap. The default is “cheapsort”. 

— n V/ Set modify mode on the index command to M. M can take the same values as the 

— r flag above. Default is “isam”. 

±a Set/clear the autoclear option in the terminal monitor. It defaults to set. 

±b Sct/reset batch update. Users must the 000002 bit set in the status field of the users 

file to clear this flag. This flag is normally set. When dear, queries will run slightly 
faster, but no recovery can take place. Queries which update a secondary index au¬ 
tomatically set this flag for that query only. 

±d Print/don't print the dayfile. Normally set. 

±s Print/don't print any of the monitor messages, including prompts. This flags is nor¬ 

mally set. If cleared, it also clears the — d flag. 

±w Wait/don't wait for (he database. If the +w flag is present. Ingres will wait if cer¬ 

tain processes are running (purge.restore, and/or sysmod) on the given data base. 
Upon completion of those processes INGRES will proceed If the —w flag is present, 
a message is returned and execution slopped if the data base is not available. If the 
+ * flag is omitted and the data base is unavailable, the error message is returned if 
inc.res is running in foreground (more precisly if the standard input is from a ter¬ 
minal), otherwise the wait option is invoked. 

Pimess mhle is the pathname of a i Nix file which may be used to specify the run-lime 
configuration of inc.res. This feature is intended for use in system maintenance only, and its 
unenlightened use by the user community is strongly discouraged 

Note It is possible to run the monitor as a batch-processing interface using the >' and T 
operators of the t nix shell, provided the input file is in proper monitor-format. 






INGRES (UNIX) 


3/14/79 


INGRES (UNIX) 


EXAMPLE 

ingrcs demo 

Ingres — d demo 

mgres — s demo < batchfile 

Ingres — f4g 12.2 — i 13 +b — rhash demo 


FILES 

.../files/users - valid INGRES users 

.../duia/base/* - data bases 

.../datadir/* — for compatability with previous versions 

.../files/proctab6.2 - runtime configuration file 

SEE ALSO 

monitor(quel) 

DIAGNOSTICS 

Too many options to Ingres — you have stated too many flags as Ingres options. 

Bad flag format — you have stated a flag in a format which is not intelligible, or a bad flag en¬ 
tirely. 

Too many parameters — you have given a database name, a process table name, and “some¬ 
thing else” which Ingres doesn’t know what to do with. 

No database name specified 

Improper database name — the database name is not legal. 

You may not access database name - according to the users file, you do not have permission to 
enter this database. 

You are not authorized to use the flag flag - the flag specified requires some special authoriza¬ 
tion, such as a bit in the users file, which you do not have. 

Database name does not exist 

You are not a valid INGRES user - you have not been entered into the users file, which means 
that you may not use INGRES at all. 

You may not specify this process table - special authorization is needed to specify process 
tables. 

Database temporarily unavailable — someone else is currently performing some operation on 
the database which makes it impossible for you to even log in. This condition should 
disappear shortly. 


- 2 - 





GEO-QUEL (UNIX) 


3/14/79 


GEO-QUEL (UNIX) 


NAME 

geoquel - GEO-QUEL data display system 
sx \oPsis 

geoquel [ — s ] [ — d 1 l — a ] l — 17* 1 [ —tn7) dbname 
DESCRIPTION 

geo-quel is a geographical interface to INGRES. 

Dbname is ihe name of an existing data base. 

The format of the graphic output depends upon the type of terminal in use. geo-quel will look 
up the terminal type at login time and produce output appropriate for that terminal. If the ter¬ 
minal in use is incapable of drawing graphic output then a display list is generated for a Tek¬ 
tronix 4014 but will only be displayed if the results are saved with SAVEMAP and then re¬ 
displayed. 

The flags are interpreted as follows: 

—s Don’t print any of the monitor messages, including prompts. This is inclusive of the 

day file. 

—d Don't print the dayfile. 

—a Disable the autoclear function in the terminal monitor. 

—IT Set the terminal type to T. T can be gt40, gt42, or 4014 for DEC’s GT40-GT42, and 
Tektronix’s 4014 respectively. 

— tn7 Do not display output but prepare the display list for a terminal of type 7, where 7 is 

from the above list. 

EXAMPLE 

geoquel demo 

geoquel -d demo 

geoquel -s demo < batchfile 

FILES 

.../files/grafile6.2 

.../files/ttytype 

SEE ALSO 

GEO-QUEL reference manual 
DIAGNOSTICS 

The diagnostics produced by GEO-QUEL are intended to be self-explanatory. Occasional mes¬ 
sages may be produced by INGRES; for an explanation of these messages see the INGRES system 
documentation. 




PRiNTR < UNIX) 


3/14/79 


PRINTR (UNIX) 


NAME 

printr - print relations 
S\ \t)PSlS 

printr l Haas ) database relation ... 


DESCRIPTION 

Pnnir prints the named relation(s) out of the database specified, exactly like the print command. 
Retrieve permission must be granted to all people to execute this command. 

Flags accepted are —u, ±w, —c, —i, —f, and —v. Their meanings are identical to the mean¬ 
ings of the same flags in INGRES. 


SEE ALSO 

ingres(unix), print(quel) 


DIAGNOSTICS 

bad flag - you have specified a flag which is not legal or is in bad format, 
you may not access database - this database is prohibited to you based on status information in 
the users file. 

cannot access database — the database does not exist. 


1 - 





PURGE (UNIX) 


3/14/79 


PURGE (UNIX) 


\ \ME 

purge - destroy all expired and temporary relations 
SYNOPSIS 

purge I —f) I —p 1 [ -a ] [ —s ] [ ±w ] ( database ... ] 

DESCRIPTION 

Purge searches the named databases deleting system temporary relations. When using the — p 
flag, expired user relations are deleted. The —f flag will cause unrecognizable files to be delet¬ 
ed, normally purge will just report these files. 

Only the database administrator (the DBA) for a database may run purge, except the INGRES 
superuser may purge any database by using the — s flag. 

If no databases are specified all databases for which you are the DBA will be purged. All data¬ 
bases will be purged if the INGRES superuser has specified the — s flag. The —a flag will cause 
purge to print a message about the pending operation and execute it only if the response if a 
Any other response is interpreted as “no”. 

Purge will lock the data base while it is being processed, since errors may occur if the database 
is active while purge is working on the database. If a data base is busy purge will report this and 
go on to the next data base, if any. If standard input is not a terminal purge will wait for the 
data base to be free. If — w flag is stated purge will not wait, regardless of standard input. The 
+ w flag causes purge to always wait. 

EXAMPLES 

purge — p +w tempdata 
purge —a -f 

SEE ALSO 

save(quel), restore(unix) 

Dl M.NOSTICS 

who are you? — you are not entered into the users file. 

not ingres superuser - you have tried to use the -s flag but you are not the INGRES su¬ 
peruser. 

you are not the dba — you have tried to purge a database for which you are not the DBA. 
cannot access database — the database does not exist. 


BIOS 

If no database names are given, only the databases located in the directory data/base are 
purged, and not the old databases in datadir. Explicit database names still work for databases 
m either directory. 


- 1 - 










• * iVt fawh frak *1 Sk. ■ jruiLW- 











RESTORE ( UNIX) 


3/14/79 


RESTORE (UNIX) 


n ami: 

restore - recover from an INGRES or UNIX crash. 

St \OPSIS 

restore l — a ] ( — s 1 [ ±w 1 ( database ... 1 
DESCRIPTION 

Restore is used to restore a data base after an Ingres or UNIX crash. It should always be run 
after any abnormal termination to ensure the integrity of the data base. 

In order to run restore, you must be the DBA for the database you are restoring or the INGRES 
superuser and specify the —s flag. 

If no databases are specified then all databases for which you are the DBA are restored. All da¬ 
tabases will be restored if the INGRES superuser has specified the — s flag. 

If the —a flag is specified you will be asked before restore takes any serious actions. It is advis¬ 
able to use this flag if you suspect the database is in bad shape. Using /dev/null as input with 
the —a flag will provide a report of problems in the data base. If there were no errors while 
restoring a database, purge will be called, with the same flags that were given to restore, to re¬ 
move unwanted files and system temporaries. Restore may be called with the — f and/or — p 
flags for purge. Unrecognized files and expired relations are not removed unless the proper 
flags are given. In the case of an incomplete destroy, create or index restore will not delete files 
for partially created or destroyed relations. Purge must be called with the — f flag to accomplish 
this. 

Restore locks the data base while it is being processed. If a data base is busy restore will report 
this and go on to the next data base. If standard input is not a terminal restore will wail for the 
data base to be free. If the —w flag is set restore will not wait regardless of standard input. If 
+ w is set it will always wait. 

Restore can recover a database from an update which had finished filling the batch file. Updates 
which did not make it to this stage should be rerun. Similarly modifies which have finished re¬ 
creating the relation will be completed (the relation relation and attribute relations will be up¬ 
dated). If a destroy was in progress it will be carried to completion, while a create will almost- 
always be backed out. Destroying a relation with an index should destroy the index so restore 
may report that a secondary relation has been found with no primary. 

If interrupt (signal 2) is received the current database is closed and the next, if any, is pro¬ 
cessed. Quit (signal 3) will cause restore to terminate. 

EXAMPLE 

restore -f demo 

restore -a grants < /dev/null 

DIAGNOSTICS 

All diagnostics are followed by a tuple from a system relations. 

“No relation for attribute(s)” - the attributes listed have no corresponding entry in the rela¬ 
tion relation 

“No primary relation for index" — the tuple primed is the relation tuple for a secondary index 
for which there is no primary relation. The primary probably was destroyed the 
secondary will be. 

“No indexes entry for primary relation" - the tuple is for a primary relation, the rel ndxd 
domain will be set to zero. This is the product of an incomplete destroy. 

"No indexes entry for index" — the tuple is for a secondary index, the index will be destroyed 
This is the product of an incomplete destroy. 

"retname is index for" — an index has been found for a primary which is not marked as in¬ 
dexed. The primary will be so marked. This is probably the product of an incom¬ 
plete index command. The index will have been created properly but not modified 
“No file for" — There is no data for this relation tuple, the tuple will be deleted. If. under the 
— a option, the tuple is not deleted purge will not be called. 


- 1 - 




RESTORE (UNIX) 


3/14/79 


RESTORE (UNIX) 


“No secondary index for indexes entry” — An entry has been found in the indexes relation for 
which the secondary index does not exist (no relation relation tuple). The entry will 
be deleted. 


SEt ALSO 

purge(unix) 


BIGS 

If no database names are given, only the databases located in the directory data/base are re¬ 
stored, and not the old databases in datadir. Explicit database names still work for databases in 
either directory. 









SYSMOD (UNIX) 


3/14/79 


SYSMOD! UNIX ) 


\ \M» 

sysmod - modify system relations to predetermined storage structures. 
synopsis 

sysmod 1 — s ) ( —w ) dbname [ relation ) ( attribute ] I indexes 1 [ tree 1 t protect ) I integri¬ 
ties | 

l)KS( KIPTION 

Sysmod will modify the relation, attribute, indexes, tree, protect, and integrities relations to 
hash unless at least one of the relation, attribute, indexes, tree, protect, or integrities parame¬ 
ters are given, in which case only those relations given as parameters are modified. The system 
relations are modified to gain maximum access performance when running Ingres. The user 
must be the data base administrator for the specified database, or be the Ingres superuser and 
have the —s flag stated. 

Sysmod should be run on a data base when it is first created and periodically thereafter to main¬ 
tain peak performance. If many relations and secondary indices are created and/or destroyed, 
st .'mod should be run more often. 

If the data base is being used while sysmod is running, errors will occur. Therefore, sysmod will 
lock the data base while it is being processed. If the data base is busy, sysmod will report this. 
If standard input is not a terminal sysmod will wait for the data base to be free. If —w flag is 
slated sysmod will not wait, regardless of standard input. The + w flag causes sysmod to always 
wail. 

The system relations are modified to hash; the relation relation is keyed on the first domain, 
the indexes, attribute, protect, and integrities relations are keyed on the first two domains, and 
ihe tree relation is keyed on domains one, two, and five. The relation and attribute relations 
have the minpages option set at 10, the indexes relation has a minpages value of S. 

NEt VI so 

modifylquel) 




TIMEFIX (UNIX) 


3/14/79 


TIMEFIX (UNIX) 


NAME 

timefix - palch INGRES binary code for correci limezone. 
s\ NOPSIS 

timefix [ —u ] 1 —s N] [ — tyyyzzz] [ —dA'] filename ... 

DESCRIPTION 

Timefix can be used to change the INGRES system to use local time. As delivered, the Ingres 
system assumes it is in the Pacific Time Zone, eight hours behind Greenwich Mean Time. 
Timefix can automatically patch the necessary INGRES code to reflect the true timezone of your 
installation. 

INGRES uses the Unix supplied routine ctime(III) for converting the UNIX base time to local 
time. Timefix is first compiled on your system in order to get the dime routine for your installa¬ 
tion. It then can correct the necessary INGRES programs at which point your Ingres system will 
be correct and not have to be changed again. 

To use timefix you must be logged in as ingres and then use the setup command: 
setup timefix 

This command performs the following steps: (1) compiles timefix.c, (2) runs timefix on the 
necessary INGRES programs. 

If for any reason, timefix.c cannot be compiled on your system, another method exists for up¬ 
dating INGRES. Timefix can be run with the local time expressed using the — s — t and — d flag 
options. Their meanings are: 

—s/V N is the number of seconds ahead/behind GMT. 

—t vvvzzz yvy and zzz are the two, three character timezone names. 

-dX if X is 0, then daylight savings time is disabled, otherwise daylight savings time 

will occur according to the rules specified in ctime(IU). 

The flags can be given in any order. You must be logged in as ingres and then use the setup 
command giving the proper time conversions. For example, in Hartford, Connecticut you 
would type: 

setup timefix — sl8000 —tESTEDT —dl 

If the — u flag is specified then timefix reports what il would do but does not actually update the 
files. 

EXAMPLES 

setup timefix 

setup timefix —si8000 — tESTEDT —dl 
DIAGNOSTICS 

Timefix depends on the existence of a namelist. If the namelist (i.e. symbol table) is not 
present then an error message is given. If all the symbols related to the dime routine cannot be 
found then it is assumed that the file need not be corrected. If the file cannot be opened for 
reading and writing then an error message is issued. 

Bl GS 

Timefix will not work for timezones which are ± 10 or ±11 hours from GMT. 


- 1 - 




Lu --'iifiilMiiii iifiiiiir rfiifttr 


Ml UNO 

ctimc (111) 




USERSETUP (UNIX) 


3/14/79 


USERSETUP (UNIX) 


NAME 

usersetup — setup users file 
SYNOPSIS 

.../bin/usersetup [ pathname ] 

DESCRIPTION 

The /etc/passwd file is read and reformatted to become the INGRES users file, stored into 
.../files/users. If pathname is specified, it replaces If pathname is the result is 

written to the standard output. 

The user name, user, and group id’s are initialized to be identical to the corresponding entry in 
the /etc/passwd file. The status field is initialized to be zero, except for user ingres, which is 
initialized to all permission bits set. The “initialization file” parameter is set to the file .Ingres 
in the user’s login directory. The user code field is initialized with sequential two-character 
codes. All other fields are initialized to be null. 

After running usersetup, the users file must be edited. Any users who are to have any special 
authorizations should have the status field changed, according to the specifications in 
users(files). To disable a user from executing INGRES entirely, completely remove her line 
from the users file. 

As UNIX users are added or deleted from the /etc/passwd file, the users file will need to be 
editted to reflect the changes. For deleted users, it is only necessary to delete the line for that 
user from the users file. To add a user, you must assign that user a code in the form "aa" and 
enter a line in the users file in the form: 

name:cc:uid:gid:status:flags:proctab:initfile.:databases 
where name is the user name (taken from the first field of the /etc/passwd file entry for this 
user), cc is the user code assigned, which must be exactly two characters long and must not be 
the same as any other existing user codes, uid and gid are the user and group ids (taken from 
the third and fourth fields in the /etc/passwd entry), status is the status bits for this user, nor¬ 
mally 000000, flags are the default flags for INGRES (on a per-user basis), proctab is the default 
process table for this user (which defaults to -proctab6.2), and databases is a list of the data¬ 
bases this user may enter. If null, she may use all databases. If the first character is a dash 
(“ — ”), the field is a comma separated list of databases which she may not enter. Otherwise, it 
is a list of databases which she may enter. 

The databases field includes the names of databases which may be created. 

Usersetup may be executed only once, to initially create the users file. 


FILES 

../files/users 

/etc/passwd 

SEE ALSO 

ingres(unix), passwd(V), users(files) 

Btr.s 

it should be able to bring the users file up to date. 


- I - 






DAYFILE( FILES) 


3/14/79 


DAYF!LE( FILES) 


NAME 

. /files/dayfilc6.1 - Ingres login message 
DESCRIPTION 

The contents of the dayfile reflect user information of general system interest, and is more or 
less analogous to /etc/motd in unix. The file has no set format; it is simply copied at login 
time to the standard output device by the monitor if the —s or — d options have not been re¬ 
quested. Moreover the dayfile is not mandatory, and its absence will not generate errors of any 
sort; the same is true when the dayfile is present but not readable. 




DBTMPLT ( HLES) 


3/14/79 


DBTMPLT (F1LF.S) 


\ wit 

./Iiles/dbtmplt6.2 - database template 
IIES1 KIPTION 

This file contains the template for a database used by creaidb. It has a set of entries for each 
relation to be created in the database. The sets of entries are separated by a blank line. Two 
blank lines or an end of file terminate the file. 

The first line of the file is the database status and the default relation status, separated by a 
colon. The rest of the file describes relations. The first line of each group gives the relation 
name followed by an optional relation status, separated by a colon. The rest of the lines in each 
group are the attribute name and the type, separated by a tab character. 

All the status fields are given in octal, and have a syntax of a single number followed by a list 
of pairs of the form 
±x±N 

which says that if the ± x flag is asserted on the creaidb command line then set (clear) the bits 
specified by N. 

The first set of entries must be for the relation catalog, and the second set must be for the attri¬ 
bute catalog. 

EXAMPLE 

3-c-l+q + 2:010023 
relation: —c —20 
relid cl2 
relowner c2 

relspec il 

attribute:-c—20 
attrelid cl2 
attowner c2 

attnamecl2 

(other relation descriptors) 

SEE ALSO 

creatdb(unix) 







ERROR (FILES) 


3/14/79 


ERROR (FILES) 


\\MK 

.../files/error6.2_? - file;, with Ingres errors 
OESt RIPTtON 

These files contain the Ingres error messages. There is one file for each thousands digit; 
hence, error number 2313 will be in file error6.2_2. 

Each file consists of a sequence of error messages with associated error numbers. When an er¬ 
ror enters the front end, the appropriate file is scanned for the correct error number. If found, 
the message is printed; otherwise, the first message parameter is printed. 

Each message has the format 

errnum <TAB> message tilde. 

Messages are terminated by the tilde character (**’). The message is scanned before printing. 
If the sequence %n is encountered (where n is a digit from 0 to 9), parameter n is substituted, 
where %0 is the first parameter. 

The parameters can be in any order. For example, an error message can reference %2 before it 
references %0. 


SEE ALSO 

error(UTIL) 

EXAMPLE 

1003 line %0, bad database name %1 

1005 In the purge of %1, 

a bad %0 caused execution to half 

1006 No process, try again.' 


- 1 - 




GRAFILE (FILES) 


3/14/79 


GRAFILE (FILES) 


\ \M»: 

/Iilcs/grafile6.2 - geo-quel login message 

DEM RIPTION 

The contents of the grafile (GEO-QUEL dayfile) reflect user information of general system in¬ 
terest, and is more or less analogous to /etc/motd in UNIX. The file has no set format; it is 
simply copied at login lime to the standard output device by geo-QUEL if the —s or — d options 
have not been requested. Moreover the grafile is not mandatory, and its absence will not gen¬ 
erate errors of any sort; the same is true when the grafile is present but not readable. 





L1BQ< FILLS) 


3/14/79 


LIBQ( FILES) 


libq — Equel run-time support library 
DESCRIPTION 

Libq all the routines necessary for an equel program to load. It resides in /Ub/libq.a, and must 
be specified when loading equel pre-processed object code. It may be referenced on the com¬ 
mand line of ccby the abbreviation — Iq. 

Several useful routines which are used by equel processes are included in the library. These 
may be employed by the equel programmer to avoid code duplication. They are: 

ini IlatoiCbuf, i) 

char *buf; 

ini i; 

char *llbmove(source, destination, len) 
char ’source, ’destination; 
int len; 

char *Ilconcatv(buf, argl, arg2.0) 

char *buf, ’argl, ...; 

char ’llitos(i) 

int i; 

int IIsequaKsl, s2) 

char *sl, *s2; 

int lllength(string) 

char ’string; 

lisyserr(string, argl, arg2, ...); 
char ’string; 


llatoi Ilatoi is equivalent to atoi(UTIL). 

Ubmove Moves len bytes from source to destination , returning a pointer to the location after 
the last byte moved. Does not append a null byte. 

Ilconcalv Concatenates into buf iW of its arguments, returning a pointer to the null byte at 
the end of the concatenation. Bit/ may not be equal to any of the arg-n but argl. 

Ilitos llitos is equivalent to itoa(III) 

Ilsequal Returns 1 iff strings si is identical to s2. 

lllength Returns maxdength of string without null byte at end. 255) 

llytscrr Hsyserr is diferrent from syserr(util) only in that it will print the name in 

llproc_name. and in that there is no 0 mode. Also, it will always call exitl-l) 
after printing the error message. 

There are also some global Equel variables which may be manipulated by the user: 

int llerrflag: 

char ’Ilmainpr; 

char (’llprinterrX); 

mi llreterrl); 

int lino errO: 







LlliQI HU S) 


3/14/79 


LIBQ( FILES) 


llerrflag Set on an error from INGRES to be the error number (see the error message sec¬ 
tion of the "Ingres Reference Manual") that ocurred. This remains valid from 
the time the error occurrs to the time when the next equel statement is issued. 
This may be used just after an equel statement to see if it succeded. 

Ilmainpr This is a string which determines which ingres to call when a '## ingres" is is¬ 
sued. Initially it is "/usr/bin/ingres". 

llprint err This function pointer is used to call a function which determines what (if any) er¬ 
ror message should be printed when an ingres error occurs. It is called from ller- 
ror() with the error number as an argument, and the error message corresponding 
to the error number returned will be printed. If (*Uprint_err)( <ermo>) returns 
0, then no error message will be printed. Initially IIprint_err is set to IIret_err() 
to print the error that ocurred. 

Ilret_err Returns its single integer argument. Used to have (*IIprint_err)() cause printing 
of the error that ocurred. 

IIno_err Returns 0. Used to have (*llprint_err)() suppress error message printing. 

Ilno err is used when an error in a parametrized equel statemenr occurs to 
suppress printing of the corresponding parser error. 

SEE ALSO 

atoi(util), bmove(utii), cc(I), equel(unix), exit (II), itoa(IU), length (util), sequal(util), 

syserr(util) 


- 2 - 





PROCTAB( FILES) 


3/14/79 


PROCTABf FILES) 


NAME 

,../files/proctab6.2 - INGRES runtime configuration information 
DESCRIPTION 

The file ,../files/proctab6.2 describes the runtime configuration of the Ingres system. 

The process table is broken up into logical sections, separated by lines with a single dollar sign. 
The first section describes the configuration of the system and the parameters to pass to each 
system module. All other sections contain strings which may be macro-substituted into the first 
section. 

Each line of the first section describes a single process. The lines consist of a series of colon- 
separated fields. 

The first field contains the pathname of the module to be executed. 

The second field is a set of flags which allow the line to be ignored in certain cases. If this field 
is null, the line is accepted; otherwise, it should be a series of items of the form “ + —— A”, 
where any of “4- - =” may be omitted, and A" is a flag which may appear on the INGRES com¬ 
mand line. The characters “ + — =” are interpreted as the sense of the flag: “ + ” will accept 
the line if the flag “ + A” is stated on the command line, “ —” will accept if “-A " is stated, 
and “=*” will accept if the “A” flag is not stated at all. These may be combined in the forms 
“ + — ” and “ — — ”, For example, the field: 

+ =& 

will acept the line if the EQUEL flag (“&’’) is stated as “+&” or is not staled, but the line will 
be ignored if the “ — &” flag is stated. 

If any flag item rejects the line, the entire line is rejected. 

The third field is a status word. The number in this word is expressed in octal. The bits have 
the following meaning. 

000010 close diagnostic output 

000004 close standard input 

000002 run in user’s directory, not database 

000001 run as the user, not as INGRES 

The fourth field is a file name to which the standard output should be redirected. It is useful 
for debugging. 

The fifth field describes the pipes which should be connected to this process. The field must be 
six characters long, with the characters corresponding to the internal variables R_up, W up, 
R down, W down, R front, and W front respectively. The characters may be a question mark, 
which leaves the pipe closed; a digit, which is filled in from the file descriptors provided by the 
EQUEL flag or the flag; or a lower case letter, which is connected via a pipe with any oth¬ 
er pipes having the same letter; this last action is done on the fly to conserve file descriptors. 

The sixth and subsequent fields are arbitrary parameters to be sent to the modules. There must 
be a colon after the fifth field even if no parameters are present, but there need not be a colon 
after the last parameter. 

The last module executed (usually the last line in the first section) becomes the parent of ail 
the other processes. 

The second through last sections of the process table consist of a single line which names the 
section followed by arbitrary text. The pathname field and all parameter fields of each line of 
the first section are scanned for strings of the form ”Sname - ': this string is replaced by the text 
from the corresponding section. For convenience, the name Spathname is automatical!) 
defined to be the pathname of the root of the INGRES subtree. 

The D3U routines want to see two parameters. The first parameter is the pathname of the 
"ksori " routine. The second parameter is a series of lines of the form. 


- 1 - 




PHOCT.ABI FILES) 


3/14/79 


PROCTAB( FILES) 


command name place Jist 

where command name is the name of one of the possible INGRES commands executed by the 
DHL routines, and placc lisi is a comma-separated list of the actual location(s) of that com¬ 
mand, Each "place” is a two-character descriptor: the first character is the overlay in which 
that command resides, and the second character is the function within that overlay. If a com¬ 
mand is in more than one place, INGRES will try to avoid calling in another overlay. For exam¬ 
ple: 

create:aO,ml 

means that the create command may be found in overlay “a” function 0 or in overlay "m” 
function 1. If already in overlay “a” or “m” the create command resident in that overlay will 
be called, otherwise, overlay “a” will be called. 

EXAMPLE 

The following example will execute a three process system unless the flag is specified (as 
when a two-process system will be executed with the monitor dropped out and the cal¬ 
ling (EQUEL) program in its place. Notice that there are two lines for the parser entry, one for 
the EQUEL case and one for the non-EQUEL case. In the EQUEL case, output from the 
parser is diverted to a file called “debug.out”. 

Spathname/bin/overlaya. :000014: :bc? ? 23 :$pathname/bin/ksort:$dbutab 
$pathname/bin/parser: + «*> &.000014: adeb??: 

$pathname/bin/parser: —&:000014:debug.out:01cb??: 

$pathname/bin/monitor:-f =&:000003::??da??:$pathname/files/startup 
$ 

dbutab 

create:aO,ml 

destroy :al, m2 

modify.mO 

help:a2 

$ 







STARTUP (FILES) 


3 / 14/79 


STARTUP (FILES) 


NAME 

../files/startup - Ingres startup file 


DESCRIPTION 

This file is read by the monitor at login time. It is read before the user startup file specified in 
the users file. The primary purpose is to define a new editor and/or shell to call with the \e or 
\s commands. 


SEE AI.SO 

monitor(quel), users(files) 





TTYrYPl < TILES) 


3/28/79 


TTYTYPE (FILES) 


\ WH 

/lilos/ttytype - gio-qih terminal type database 

UESt Rll’l ION 

The ttytype tile describes each terminal on your system, geo-quel will not attempt to display 
graphical output on terminals that are not capable of displaying it. There is a sample of the file 
in .../geo<|uel/ttytype.sainple. This is a copy of the file in use on the Berkeley system. 

The ttytype file consists of a series of lines; the first character is the terminal id, and the rest of 
the line tells the type of the terminal. The first of these characters is a terminal class, and the 
rest signify the brand, or some other more descriptive indication. A completely blank line ter¬ 
minates the useful part of the file, after which comments may appear unrestricted. In the sam¬ 
ple file the currently recognized (defined) terminal types are listed as comments. 


BIGS 

The current version of geo-quel only looks for terminals of graphic nature and therefore only 
the graphic terminals need be in this database. If any other system or sub-system wishes to use 
this file, all terminals must be kept up to date. 



- 1 - 



v. t 

’ ad 







USERS ( FILES) 


3/14/79 


USERS (FILES) 


\ wit: 

. ./liles/users - Ingres user codes and parameters 
DESCRIPTION 

This file contains the user information in fields seperated by colons. The fields are as follows: 

* User name, taken directly from /etc/passwd file. 

* User code, assigned by the INGRES super-user. It must be a unique two character code. 

* l nix user id. This MUST match the entry in the /etc/passwd file. 

* Unix group id. Same comment applies. 

* Status word in octal. Bit values are: 

0000001 creatdb permission 

0000002 permits batch update override 

0000004 permits update of system catalogs 

0000020 can use trace flags 

0000040 can turn off qrymod 

0000100 can use arbitrary proctabs 

0000200 can use the =proctab form 

0100000 ingres superuser 

* A list of flags automatically set for this user. 

* The process table to use for this user. 

* An initialization file to read be read by the monitor at login time. 

* Unassigned. 

* Comma seperated list of databases. If this list is null, the user may enter any database. If it 

begins with a ‘ — ’, the user may enter any database except the named databases. Oth¬ 
erwise, the user may only enter the named databases. 

EXAMPLE 

ingres:aa:5:2:177777:—d:=special./mnt/ingres/.ingres:: 
guest:ah:35:l:000000:::::demo,guest 

SEE ALSO 

initucode(util) 





INTRODUCTION (ERROR) 


3/30/79 


INTRODUCTION (ERROR) 


name 

Error messages introduction 
DESCRIPTION 

This document describes the error returns which are possible from the INGRES data base system 
and gives an explanation of the probabie reason for their occurrence. In ail cases the errors are 
numbered ru cor where n indicates the source of the error, according to the following table: 

1 — equel preprocessor 

2 — parser 

3 “ query modification 

4 — decomposition and one variable query processor 

5 — data base utilities 
30 - GEO-QUEL errors 

For a description of these routines the reader is referred to The Design and Implementation of 
INGRES. The xxx in an error number is an arbitrary identifier. 

The error messages are stored in the file .../files/error6.2_n, where n is defined as above. The 
format of these files is the error number, a tab character, the message to be primed, and the 
tilde character to delimit the message. 

In addition many error messages have “%/’ in their body where i is a digit interpreted as an 
offset into a list of parameters returned by the source of the error. This indicates that a param¬ 
eter will be inserted by the error handler into the error return. In most cases this parameter 
will be self explanatory in meaning. 

Where the error message is thought to be completely self explanatory, no additional description 
is provided. 



EQUEL! ERROR) 


EQUEL(ERROR) 


3/30/79 


NAME 

EQUEL error message summary 
SYNOPSIS 

Error numbers 1000 - 1999. 

Description 

The following errors can be generated at run time by EQUEL programs. 

ERRORS 

1000 In domain %0 numeric retrieved into char field. 

Equel does not support conversion at run-time of numeric data from the data base to 
character string representation. Hence, if you attempt to assign a domain of numeric 
type to a C-variable of type character string, you will get this error message. To con¬ 
vert numerics to characters use the 'ascii” function in quel. 

1001 Numeric overflow during retrieve on domain %0. < 

You will get this error if you attempt to assign a numeric data base domain to a C- 
variable of a numeric type but with a shorter length. In this case the conversion 
routines may generate an overflow. For example, this error will result from an attempt 
to retrieve a large floating point number into a C-variable of type integer. 

1002 In domain %0, character retrieved into numeric variable. 

This error is the converse of error 1000. 

1003 Bad type in target list of parameterized retrieve ”%0”. 

Valid types are %f8, %f4, %i4, %i2, %c. 

1004 Bad type in target list of parameterized statement *%0'. 

Valid types are %f8, %f4, %i4, %i2, %il, %c. 


- 1 - 


P 




PARSER (ERROR ) 


3/30/79 


PARSERiERROR) 


NAME 

Parser error message summary 
SYNOPSIS 

Error numbers 2000 - 2999. 

DESCRIPTION 

The following errors can be generated by the parser. The parser reads your query and translates 
it into the appropriate internal form; thus, almost all of these errors indicate syntax or type 
conflict problems. 

ERRORS 

2100 line %0, Attribute '%t' not in relation '%2' 

This indicates that in a given line of the executed workspace the indicated attribute 
name is not a domain in the indicated relation. 

2103 line %0, Function type does not match type of attribute '%1' 

This error will be returned if a function expecting numeric data is given a character 
string or vice versa. For example, it is illegal to take the SIN of a character domain. 

2106 line %0, Data base utility command buffer overflow 

This error will result if a utility command is too long for the buffer space allocated to it 
in the parser. You must shorten the command or recompile the parser. 

2107 line %0, You are not allowed to update this relation: %1 

This error will be returned if you attempt to update any system relation or secondary’ 
index directly in QUEL (such as the RELATION relation). Such operations which 
compromise the integrity of the data base are not allowed. 

2108 line %0, Invalid result relation for APPEND ’%1' 

This error message will occur if you execute an append command to a relation that 
does not exist, or that you cannot access. For example, append to junk( ... ) will fail if 
junk does not exist. 

2109 line %0, Variable '%Y not declared in RANGE statement 

Here, a symbol was used in a QUEL expression in a place where a tuple variable was 
expected and this synbol was not defined via a RANGE statement. 

2111 line %0, Too many attributes in key for INDEX 

A secondary index may have no more than 6 keys. 

2117 line %0, Invalid relation name -n/ o 1' in RANGE statement 

You are declaring a tuple variable which ranges over a relation which does not exist. 

2118 line %0. Out of space in query tree - Query too long 

You have the misfortune of creating a query which is too long for the parser to digest. 
The only options are to shorten the query or recompile the parser to have more buffer 
space for the query tree. 

2119 line %0, MOD operator not defined for floating point or character attributes 
The mod operator is only denned for integers. 

2120 line %0. no pattern match operators allowed in the target list 

Pattern match operators (such as “*”) can only be used in a qualification. 

2121 line %0. Only character type domains are allowed in CONCAT operator 


• 1 - 





PARSER(ERROR) 


3/30/79 


PARSER (ERROR > 


2123 line %0,'% 1 .all' not defined for replace 

2125 line %0. Cannot use aggregates ("avg" or "avgu") on character values 

2126 line %0. Cannot use aggregates ("sum" or "sumu") on character values 

2127 line %0. Cannot use numerical functions (ATAN, COS, GAMMA, LOG, SIN, SQRT, 

EXP, ABS) on character values 

2128 line %0, Cannot use unary operators (" + " or "—*) on character values 

2129 line %0, Numeric operations (+ — * /) not allowed on character values 

Many functions and operators are meaningless when applied to character values. 

2130 line %0, Too many result domains in target list 

Maximum number of result domains is MAXDOM (currently 49). 

2132 line %0, Too many aggregates in this query 

Maximum number of aggregates allowed in a query is MAXAGG (currently 49). 

2133 line %0. Type conflict on relational operator 

It is not legal to compare a character type to a numeric type. 

2134 line %0. '%!' is not a constant operator. 

Only 'dba' or 'usercode' are allowed. 

2135 line %0, You cannot duplicate the name of an existing relation(%1) 

You have tried to create a relation which would redefine an existing relation. Choose 
another name. 

2136 line %0, There is no such hour as %1, use a 24 hour dock system 

2137 line %0, There is no such minute as %1. use a 24 hour clock system 

2138 line %0, There is no such time as 24:%1. use a 24 hour clock system 

Errors 2136-38 indicate that you have used a bad time in a permit statement. Legal 
times are from 0:00 to 24:00 inclusive. 

2139 line %0, Your database does not support query modification 

You have tried to issue a query modification statement ( define ), but the database was 
created with the — q flag. To use the facilities made available by query modification, 
you must say: 

creatdb — e +q dbname 

to the shell. 

2500 syntax error on line %0 
last symbol read was: %1 

A 2500 error is reported by the parser if it cannot otherwise classify the error. One 
common wav to obtain this error is to omit the required parentheses around the target 
list. The parser reports the last symbol which was obtained from the scanner. Some¬ 
times, the last symbol is far ahead of the actual place where the error occurred. The 
string "EOF is used for the last symbol when the parser has read past the query. 

2502 line %0. The word cannot follow a RETRIEVE command, therefore the com¬ 
mand was not executed. 

2503 line %0, The word cannot follow an APPEND command, therefore the command 

was not executed. 

2504 line %0, The word cannot follow a REPLACE command, therefore the command 

was not executed. 

2505 line %0, The word cannot follow a DELETE command, therefore the command 

was not executed. 

2506 line %0. The word '%1\ cannot follow a DESTROY command, therefore the com¬ 
mand was not executed. 

2507 line %0. The word cannot follow a HELP command, therefore the command was 


2 - 







PARSER < ERROR ) 


3/30/79 


PARSER (ERROR) 


not executed. 

2508 line %0, The word '%1\ cannot follow a MODIFY command, therefore the command 
was not executed. 

2509 line %0, The word '%1\ cannot follow a PRINT command, therefore the command 
was not executed. 

2510 line %0, The word '%1\ cannot follow a RETRIEVE UNIQUE command, therefore 
the command was not executed. 

2511 line %0, The word cannot follow a DEFINE VIEW command, therefore the 
command was not executed. 

2512 line %0. The word '%1\ cannot follow a HELP VIEW, HELP INTEGRITY, or HELP 
PERMIT command, therefore the command was not executed. 

2513 line %0, The word cannot follow a DEFINE PERMIT command, therefore the 

command was not executed. 

2514 line %0, The word cannot follow a DEFINE INTEGRITY command, therefore 

the command was not executed. 

2515 line %0, The word '%1\ cannot follow a DESTROY INTEGRITY or DESTROY PER¬ 
MIT command, therefore the command was not executed. 

Errors 2502 through 2515 indicate that after an otherwise valid query, there was some¬ 
thing which could not begin another command. The query was therefore aborted, 
since this could have been caused by misspelling where or something equally as 
dangerous. 

2700 line %0, non-terminated string 

You have omitted the required string terminator ("). 

2701 line %0, siring too long 

Somehow, you have had the persistence or misfortune to enter a character string con¬ 
stant longer than 255 characters. 

2702 line %0, invalid operator 

You have entered a character which is not alphanumeric, but which is not a defined 
operator, for example, *?". 

2703 line %0, Name too long *%1' 

In INGRES relation names and domain names are limited to 12 characters. 

2704 line %0. Out of space in symbol table - Query too long 

Your query is too big to process. Try breaking it up with more \go commands. 

2705 line %0, non-terminated comment 

You have left off the comment terminator symbol ("•/"). 

2707 line %0, bad floating constant: %1 

Either your floating constant was incorrectly specified or it was too large or too small. 
Currently, overflow and underflow are not checked. 

2708 line %0, control character passed in pre-converted siring 

In EQl'EL a control character became embedded in a siring and was not caught until the 
scanner was processing it. 

2709 line %0, buffer overflow in converting a number 

Numbers cannot exceed 256 characters in length. This shouldn't become a problem 
until number formats in INGRES are increased greatly. 








QRYMOD( ERROR) 


3/30/79 


QRY.MOD (ERROR) 


NAME 

Query Modification error message summary 
SYNOPSIS 

Error numbers 3000 — 3999. 

DESCRIPTION 

These error messages are generated by the Query Modification module. These errors include 
syntactic and semantic problems from view, integrity, and protection definition, as well as run 
time errors — such as inability to update a view, or a protection violation. 

ERRORS 

3310 %0 on view % 1: cannot update some domain 

You tried to perform operation %0 on a view: however, that update is not defined. 

3320 %0 on view %1: domain occurs in qualification of view 

It is not possible to update a domain in the qualification of a view, since this could 
cause the tuple to disappear from the view. 

3330 %o on view %1: update would result in more than one query 

You tried to perform some update on a view which would update two underlying rela¬ 
tions. 

3340 %0 on view %l: views do not have TID’s 

You tried to use the Tuple IDentifier field of a view, which is undefined. 

3350 %0 on view %1; cannot update an aggregate value 

You cannot update a value which is defined in the view definition as an aggregate. 

3360 %0 on view %1: that update might be non-functional 

There is a chance that the resulting update would be non-functional, that is. that it 
may have some unexpected side effects. rNGRES takes the attitude that it is better to 
not try the update. 

3490 INTEGRITY on %1: cannot handle aggregates yet 

You cannot define integrity constraints which include aggregates. 

3491 INTEGRITY on %1: cannot handle multivariable constraints 

You cannot define integrity constraints on more than a single variable. 

3492 INTEGRITY on %1: constraint does not initially hold 

When you defined the constraint, there were already tuples in the relation which did 
not satisfy the constraint. You must fix the relation so that the constraint holds before 
you can declare the constraint. 

3493 INTEGRITY on %l: is a view 

You can not define integrity constraints on views. 

3494 INTEGRITY on %1: You must own '%!' 

You must own the relation when you declare integrity constraints. 

3500 %0 on relation %l: protection violation 

You have tried to perform an operation which is not permitted to you. 

3590 PERMIT: bad terminal identifier "%2" 

In a permit statement, the terminal identifier field was improper. 




QRYMOD (ERROR) 


3/30/79 


QRYMOD (ERROR) 


3591 PERMIT: bad user name "%2“ 

You have used a user name which is not defined on the system. 

3592 PERMIT: Relation '%1' not owned by you 

You must own the relation before issuing protection constraints. 

3593 PERMIT: Relation '%1' must be a real relation (not a view) 

You can not define permissions on views. 

3594 PERMIT on %1: bad day-of-week'%2' 

The day-of-week code was unrecognized. 

3595 PERMIT on %1: only the DBA can use the PERMIT statement 

Since only the DBA can have shared relations, only the DBA can issue permit state¬ 
ments. 

3700 Tree buffer overflow in query modification 

3701 Tree build stack overflow in query modification 

Bad news. An internal buffer has overflowed. Some expression is too large. Try mak¬ 
ing your expressions smaller. 








OVQP(ERROR) 


3/30/79 


OVQP(ERROR) 


NAME 

One Variable Query Processor error message summary 
SYNOPSIS 

Error numbers 4000 — 4499. 

DESCRIPTION 

These error messages can be generated at run time. The One Variable Query Processor actually 
references the data, processing the tree produced by the parser. Thus, these error messages are 
associated with type conflicts detected at run time. 

ERRORS 

4100 OVQP query list overflowed 

This error is produced in the unlikely event that the internal form of your interaction 
requires more space in the one variable query processor than has been allocated for a 
query buffer. There is not much you can do except shorten your interaction or recom¬ 
pile OVQP with a larger query buffer. 

4101 numeric operation using char and numeric domains not allowed 

Occasionally, you will be notified by OVQP of such a type mismatch on arithmetic 
operations. This only happens if the parser has not recognized the problem. 

4102 unary operators are not allowed on character values 

4103 binary operators cannot accept combinations of char and numeric fields 

4104 cannot use aggregate operator "sum" on character domains 
41 OS cannot use aggregate operator "avg" on character domains 

These errors indicate type mismatches - such as trying to add a number to a character 
string. 

4106 the interpreters stack overflowed — query too long 

4107 the buffer for ASCII and CONCAT commands overflowed 

More buffer overflows. 

4108 cannot use arithmetic operators on two character fields 

4109 cannot use numeric values with CONCAT operator 

You have tried to perform a numeric operation on character fields. 

4110 floating point exception occurred. 

If you have floating point hardware instead of the floating point software interpreter, 
you will get this error upon a floating point exception (underflow or overflow) Since 
the software interpreter ignores such exceptions, this error is only possible with float¬ 
ing point hardware. 

4111 character value cannot be converted to numeric due to incorrect syntax. 

When using inti, int2. int4, float4, or floac8 to convert a character to value to a 
numeric value, the character value must have the proper syntax. This error will occur 
if the character value contained non-numeric characters. 

4112 ovqp query vector overflowed 
Similar to error 4100. 

4199 you must convert your 6.0 secondary index before running this query! 

The internal format of secondary indices was changed between versions 6.0 and 6.1 of 
INGRES. Before deciding to use a secondary index OVQP checks that it is not a 6.0 in¬ 
dex. The solution is to destroy the secondary index and recreate it. 






DECOMP(ERROR ) 


3/30/79 


DECOMP ( ERROR ) 


"SAME 

Decomposition error message summary 
SYNOPSIS 

Error numbers 4500 - 4999. 

DESCRIPTION 

These error messages are associated with the process of decomposing a multi-variable query 
into a sequence of one variable queries which can be executed by OVQP. 

ERRORS 

4602 query involves too many relations to create aggregate function intermediate result. 

In the processing of aggregate functions it is usually necessary to create an intermedi¬ 
ate relation for each aggregate function. However, no query may have more than ten 
variables. Since aggregate functions implicitly increase the number of variables in the 
query, you can exceed this limit. You must either break the interaction apart and pro¬ 
cess the aggregat functions separately or you must recompile INGRES to support more 
variables per query. 

4610 Query too long for available buffer space (qbufsize). 

4611 Query too long for available buffer space (varbufsiz) 

4612 Query too long for available buffer space (sqsiz) 

4613 Query too long for available buffer space (stacksiz) 

4614 Query too long for available buffer space (agbufsiz). 

These will happen if the internal form of the interaction processed by decomp is too 
long for the available buffer space. You must either shorten your interaction or 
recompile decomp. The name in parenthesis gives the internal name of which buffer 
was ioo small. 

4615 Aggregate function is too wide or has too many domains. 

The internal form of an aggregate function must not contain more than 49 domains or 
be more than 498 bytes wide. Try breaking the aggregate function into two or more 
parts. 

4620 Target list for "retrieve unique" has more than 49 domains or is wider than 498 bytes. 


- 1 - 


i 




DBU<ERROR > 


3/30/79 


DBU(ERROR ) 


NAME 

Daia Base Utility error message summary 
SYNOPSIS 

Error numbers 5000 — 5999 
DESCRIPTION 

The Data Base Utility functions perform almost all tasks which are not directly associated with 
processing queries. The error messages which they can generate result from some syntax 
checking and a considerable amount of semantic checking. 

ERRORS 

5001 PRINT: bad relation name %0 

You are trying to prim a relation which doesn’t exist. 

5002 PRINT: %0 is a view and can’t be printed 
The only way to print a view is by retrieving it. 

5003 PRINT: Relation %0 is protected. 

You are not authorized to access this relation. 

5102 CREATE: duplicate relation name %0 

You are trying to create a relation which already exists. 

5103 CREATE: %0 is a system relation 

You cannot create a relation with the same name as a system relation. The system 
depends on the fact that the system relations are unique. 

5104 CREATE %0: invalid attribute name %I 

This will happen if you try to create a relation with an attribute longer than 12 charac¬ 
ters. 

5105 CREATE %0: duplicate attribute name %1 

Attribute names in a relation must be unique. You are trying to create one with a du¬ 
plicated name. 

5106 CREATE %0: invalid attribute format "%2" on attribute %1 

The allowed formats for a domain are cl —c255, il. i2, i4, f4 and f8. Any other for¬ 
mat will generate this error. 

5107 CREATE %0: excessive domain count on attribute %1 

A relation cannot have more than 49 domains. The origin of this magic number is ob¬ 
scure. This is very difficult to change. 

5108 CREATE %0: excessive relation width on attribute %1 

The maximum number of bytes allowed in a tuple is 498. This results from the deci¬ 
sion that a tupie must fit on one UNIX "page". Assorted pointers require the 14 bytes 
which separates 498 from 512. This "magic number" is very hard to change. 

5201 DESTROY: %0 is a system relation 

The system would immediately stop working if you were allowed to do this. 

5202 DESTROY: %0 does not exist or is not owned by you 
To destroy a relation, it must exist, and you must own it. 

5203 DESTROY: %0 is an invalid integrity constraint identifier 

Integers given do not identify integrity constraints on the specified relation. For exam¬ 
ple: If you were to type "destroy permit parts 1, 2, 3". and 1, 2. or 3 were not the 


- 1 - 







_ . 







DBU(ERROR) 


3/30/79 


DBU(ERROR) 


numbers "help permit parts" prints out for permissions on parts, you would get this er¬ 
ror. 

5204 DESTROY: %0 is an invalid protection constraint identifier 

Integers given do not identify protection constraints on the specified relation. Example 
as for error 5203. 

5300 INDEX: cannot find primary relation 

The relation does not exist — check your spelling. 

5301 INDEX: more than maximum number of domains 

A secondary index can be created on at most six domains. 

5302 INDEX: invalid domain %0 

You have tried to create an index on a domain which does not exist. 

5303 INDEX: relation %0 not owned by you 

You must own relations to put indicies on them. 

5304 INDEX: relation %0 is already an index 
INGRES does not permit tertiary indicies. 

5305 INDEX: relation %0 is a system relation 

Secondary indices cannot be created on system relations. 

5306 INDEX: %0 is a view and an index can’t be built on it 

Since views are not physically stored in the database, you cannot build indicies on 
them. 

5401 HELP: relation %0 does not exist 

5402 HELP: cannot find manual section " 0/ oO” 

Either the desired manual section does not exist, or yout system does not have any 
on-line documentation. 

5403 HELP: relation %0 is not a view 

Did a "help view" (which prints view definition) on a nonview. For example: "help 
view overpaidv" prints out overpaidv's view definition. 

5404 HELP: relation %0 has no permissions on it granted 

5405 HELP: relation %0 has no integrity constraints on it 

You have tried to print the permissions or integrity constraints on a relation which has 
none specified. 

5410 HELP: tree buffer overflowed 

5411 HELP: tree stack overflowed 

Still more buffer overflows. 

5500 MODIFY': relation %0 does not exist 

5501 MODIFY: you do not own relation %0 

You cannot modify the storage structure of a relation you do not own. 

5 502 MODIFY %0: you may not provide keys on a heap 
By definition, heaps do not have keys. 

■'<" MODIFY' ^>0: too many keys provided 

v 'u can only have 49 keys on any relation. 





DBU(ERROR) 


3/30/79 


DBU(ERROR) 


5504 MODIFY %0: cannot modify system relation 

System relations can only be modified by using the svsmod command to the shell; for 
example 

sysmod dbname 

5507 MODIFY %0: duplicate key "%1" 

You may only specify a domain as a key once. 

5508 MODIFY %0: key width (%1) too large for isam 

When modifying a relation to isam, the sum of the width of the key fields cannot 
exceed 245 bytes. 

5510 MODIFY %0: bad storage structure "%!’ 

The valid storage structure names are heap, cheap, isam, cisam, hash, and chash. 

5511 MODIFY %0: bad attribute name "%1" 

You have specified an attribute that does not exist in the relation. 

5512 MODIFY %0: "%1" not allowed or specified more than once 

You have specified a parameter which conflicts with another parameter, is inconsistant 
with the storage mode, or which has already been specified. 

5513 MODIFY %0: fillfactor value %1 out of bounds 
Fillfactor must be between 1 and 100 percent. 

5514 MODIFY %0: minpages value %1 out of bounds 
Min pages must be greater than zero. 

5515 MODIFY %0: "%1" should be "fillfactor", "maxpages", or "minpages" 

You have specified an unknown parameter to modify. 

5516 MODIFY %0: maxpages value %1 out of bounds 

5517 MODIFY %0: minpages value exceeds maxpages value 

5518 MODIFY %0: invalid sequence specifier "%l" for domain %2. 

Sequence specifier may be “ascending” (or “a”) or “descending” (or “d”) in a modi¬ 
fy. For example: 

modify parts to heapsort on 

pnumiascending, 

pname:descending 

5519 MODIFY: %0 is a view and can’t be modified 
Only physical relations can be modified. 

5520 MODIFY: %0: sequence specifier "%1" on domain %2 is not allowed with the specified 
storage structure. 

Sortorder may be supplied only when modifying to heapsort or cheapsort. 

5600 SAVE; cannot save system relation "%0" 

System relations have no save date and are guaranteed to stay for the lifetime of the 
data base. 

5601 SAVE: bad month "%0" 

5602 SAVE: bad day "%0" 

5603 SAVE, bad year "%0" 


- 3 - 









DBU(ERROR) 


3/30/79 


DBU(ERROR) 


This was a bad month, bad day. or maybe even a bad year for rNGRES. 

5604 SAVE: relation %0 does not exist or is not owned by you 

5800 COPY: relation %0 doesn't exist 

5801 COPY: attribute %0 in relation %1 doesn’t exist or it has been listed twice 

5803 COPY: too many attributes 

Each dummy domain and real domain listed in the copy statement count as one attri¬ 
bute. The limit is 150 attributes. 

5804 COPY: bad length for attribute %0. Length*“"%l" 

5805 COPY: can't open file %0 

On a copy “from", the file is not readable by the user. 

5806 COPY: can’t create file %0 

On a copy "into", the file is not creatable by the user. This is usually caused by the 
user not having write permission in the specified directory. 

5807 COPY: unrecognizable dummy domain "%0" 

On a copy "into", a dummy domain name is used to insert certain characters into the 
unix file. The domain name given is not valid. 

5808 COPY: domain %0 size too small for conversion. 

There were %2 tuples successfully copied from %3 into %4 

When doing any copy except character to character, copy checks ihat the field is large 
enough to hold the value being copied. 

5809 COPY: bad input string for domain %0. Input was "% 1". There were %2 tuples suc¬ 
cessfully copied from %3 into %4 

This occurs when converting character strings to integers or floating point numbers. 
The character string contains something other than numeric characters ( 0- 
9,+,—.blank.etc.). 

5810 COPY: unexpected end of file while filling domain %0. 

There were %1 tuples successfully copied from %2 into %3 

5811 COPY: bad type for attribute %0. Type*“"%l" 

The only accepted types are i, f, c, and d. 

5812 COPY: The relation "W has a secondary index. The index(es) must be destroyed be¬ 
fore doing a copy "from" 

Copy cannot update secondary indices. Therefore, a copy "from" cannot be done on 
an indexed relation. 

5813 COPY: You are not allowed to update the relation %0 
You cannot copy into a system relation or secondary index. 

5814 COPY: You do not own the relation %0. 

You cannot use copy to update a relation which you do not own. A copy "into" is al¬ 
lowed but a copy "from" is not. 

5815 COPY: An unterminated "cO" field occurred while filling domain %0. There were %1 
tuples successfully copied from %2 into %3 

A string read on a copy "from" using the "cO" option cannot be longer than 1024 char¬ 
acters. 

58 !o COPY. The full pathname must be specified for the file %0 


- 4 - 






DBU(ERROR) 


3/30/79 


DBU(ERROR) 


The file name for copy must start with a 7". 

5817 COPY: The maximum width of the output file cannot exceed 1024 bytes per tuple 

The amount of data to be output to the file for each tuple exceeds 1024. This usually 
happens only if a format was mistyped or a lot of large dummy domains were specified. 

5818 COPY: %0 is a view and can’t be copied 
Only physical relations can be copied. 

5819 COPY: Warning: %0 duplicate tuples were ignored. 

On a copy "from", duplicate tuples were present in the relation. 

5820 COPY: Warning: %0 domains had control characters which were converted to blanks. 

5821 COPY: Warning: %0 cO character domains were truncated. 

Character domains in cO format are of the same length as the domain length. You had 
a domain value greater than this length, and it was truncated. 

5822 COPY: Relation %0 is protected. 

You are not authorized to access this relation. 





GEOQUEL(ERROR) 


3/30/79 


GEOQUEL<ERROR) 


NAME 

geo-quel error message summary 
SYNOPSIS 

Error numbers 30000 — 30999. 

DESCRIPTION 

The following errors can be generated by the GEO-QUEL subsystem of rNGRES. These errors are 
all associated with errors in the graphics processor. 

ERRORS 

30210 GEO-QUEL is creating a MAPRELATION relation 

30300 line %0, In attempting to do a MAP, SHADE, or OVERLAY the relation '%T does 
not exist or is not owned by you 

30301 line %0. Failed to obtain information to put a tuple in MAPRELATION relation 
30310 line %0. Failed to complete MAP 

30330 line %0. Failed while building temporary relation in SHADE command 

30331 line %0, Maximum polygon value is 0.0 which causes floating point exception 

30332 line %0, Too many sides (maxsidel in polygon (zoneid: %1, groupid: %2) 

30340 line %0, Failed while trying to obtain range limits for axes in POINTGRAPH or LINE- 
GRAPH 

30341 line %0, The linetype specified (%1) in the linegraph command does not make sense 
for the device 

30342 line %0, %I does not exist or cannot be accessed by you 
30350 line %0. There is no current center definition for this map: %1 

30400 line %0, Error in creating destination file '%1' in SAVEMAP 

30401 line %0, Too many domains for SHADE(shadedoms) 

30402 line %0, Too many domains for POINTGRAPH of LINEGRAPH (graphdoms) 

30410 line %0. Error in creating destination file '%1' in SAVEMAP 

30420 line %Q, You may specify only one boundary when using 'cellcount' and cellwadth' 

30421 line °/<i0, Only one cellwidth per command has meaning 

30422 line %0, Only one cellcount per command has meaning 

30423 line 0/ o0. Oniy one upper bound per command has meaning 

30424 line %0, Only one lower bound per command has meaning 

30425 line %0. does not exist or cannot be accessed by you